Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Reorganize Subsections in the Intro to Contributing #233

Merged
merged 13 commits into from
Dec 14, 2023
Merged

docs: Reorganize Subsections in the Intro to Contributing #233

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
cfa940c
fix: items format in sidebars.js
adiati98 Dec 10, 2023
70d5e8e
Fix typo in faqs.md
adiati98 Dec 10, 2023
74dfeaf
docs(introduction-to-contributing.md): reorganize sections for better…
adiati98 Dec 10, 2023
118c1a7
docs(introduction-to-contributing.md): add h2 of Getting Started
adiati98 Dec 10, 2023
d21c985
docs(introduction-to-contributing.md): adjust headings level in Getti…
adiati98 Dec 10, 2023
b98ad29
docs: rename title from Setup to Setting Up Projects Locally"
adiati98 Dec 10, 2023
7d0ab72
docs(introduction-to-contributing.md): adjust wordings in the Triage …
adiati98 Dec 10, 2023
6b602db
Merge branch 'main' of https://github.com/open-sauced/docs into docs/…
adiati98 Dec 11, 2023
5e9e59d
docs: adjust wordings in the Commit section
adiati98 Dec 11, 2023
38b24b5
docs: add short description of npm-ci
adiati98 Dec 11, 2023
83488e1
Revert "fix: items format in sidebars.js"
adiati98 Dec 12, 2023
57bc935
docs: change branch naming example
adiati98 Dec 12, 2023
4f88376
docs: add tips for PR title naming
adiati98 Dec 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 78 additions & 72 deletions docs/contributing/introduction-to-contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,73 +16,36 @@ please read the [code of conduct](./code-of-conduct.md) and follow the direction
3. Always review your code first. Run the project locally and test it before requesting a review.
4. Always communicate in the GitHub repository. Whether in the issue or the pull request, keeping the lines of communication open and visible to everyone on the team helps everyone around you.

## Setup

1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository you're working on from [github/open-sauced](https://github.com/open-sauced) to your own GitHub account.
2. Clone the forked repository to your local machine.
3. Check the project's README to determine how to run the project locally.

For many of our repositories, you'll find the directions below work for running the project locally:

Run `npm ci` to install the dependencies and set up the project.

You can also use the shell commands below to get started once you have forked the repository:

```shell
git clone https://github.com/<GITHUB_USERNAME>/<REPO_NAME>.git
cd <REPO_NAME>
npm ci
```

Make sure to replace `<GITHUB_USERNAME>` with your GitHub username.

## Building

To generate a production-ready version of your code, run:

```shell
npm run build
```

## Testing
## Issues

For running the test suite, use the following command:
If you wish to work on an open issue, please comment on the issue with `.take`, and it will be assigned to you. If an issue is not assigned, it is assumed to be available for anyone to work on. Please assign yourself to an issue before working on it to avoid conflicts.

```shell
# the tests will run in watch mode by default
npm test
```
If you contribute to the project for the first time, you can search for issues with `good first issue` or `bug` labels in the repository.

Since the tests run in watch mode by default, some users may encounter errors about too many files being open. In this case, it may be beneficial to [install Watchman](https://facebook.github.io/watchman/docs/install.html).
In case you get stuck, feel free to ask for help in the [Discord](https://discord.gg/U2peSNf23P) server or [GitHub Discussions](https://github.com/orgs/open-sauced/discussions).

Check out this course, [Testing JavaScript](https://testingjavascript.com/), for more info on testing React and JavaScript.
Please follow our [code of conduct](./code-of-conduct.md) in all your interactions with the project and its contributors.

## Applying Lint Styleguide
## Commits
adiati98 marked this conversation as resolved.
Show resolved Hide resolved

To check the code for formatting and linting errors, run the following command:
When contributing to OpenSauced projects, use this command to follow our conventional commits:

```shell
npm run lint
npm run push
```

These errors will also be displayed during development but won't prevent the code from compiling.

To fix the formatting and linting errors, run the following command instead:

```shell
npm run format
```
The `npm run push` command is an interactive replacement for `git commit`. It enforces the conventional commit specification for writing commit messages, making it easier for developers and maintainers to understand the changes made in a particular commit.

These commands use [ESLint](https://eslint.org/) to check and fix the code.
After running this command, you can push your changes to the remote repo.

If you forget to run this command, automated PR checks will also run these commands, but the PR will be blocked if there are any errors.
See [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for more examples.

## Pull Requests (PR)

**_We actively welcome your pull requests. However, you must link your work to an existing issue._**

1. Fork the repo and create your branch from the default branch.
2. Name your branch to something descriptive of your work, i.e., `add-navbar` or `fix-style`.
2. Name your branch to something descriptive of your work, i.e., `add-navbar` or `fix/broken-links`.
3. If you've added code that should be tested, add tests.
4. If you've changed APIs, update the documentation.
5. If you make visual changes, screenshots are required.
Expand All @@ -91,11 +54,11 @@ If you forget to run this command, automated PR checks will also run these comma
8. If you improve the existing code, please let us know in your PR description.
9. Completing the PR form is required. Make sure to fill in the PR title, description, [link to an issue](https://help.github.com/en/github/writing-on-github/autolinked-references-and-urls), and all the necessary areas.

- The title is required to begin with "feat:" or "fix:"
- Unsolicited code is welcomed, but an issue is required to announce your intentions. **_PRs without a linked issue will be marked invalid and closed_**.
- The title must begin with "feat:", "fix:", or anything related to your changes. <br /> **Tips**: You can follow your chosen option when [committing](#commits) your changes.

> _**Note for maintainers**: All PRs need a label to assist automation. See [this guide](./triage-guide.md#adding-issue-and-pr-labels) to determine which labels to use._
- Unsolicited code is welcomed, but an issue is required to announce your intentions. <br /> **_PRs without a linked issue will be marked invalid and closed_**.

> _**Note for maintainers**: All PRs need a label to assist automation. See [this guide](./triage-guide.md#adding-issue-and-pr-labels) to determine which labels to use._

### PR Validation

Expand All @@ -115,52 +78,95 @@ GitHub supports [draft pull requests](https://github.blog/2019-02-14-introducing

- _[3 tips for getting your Pull Request reviewed on GitHub](https://youtu.be/cuMeC-eZJJ4)_

## Commits
## Getting Started

### Setting Up Projects Locally

1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository you're working on from [github/open-sauced](https://github.com/open-sauced) to your own GitHub account.
2. Clone the forked repository to your local machine.
3. Check the project's README to determine how to run the project locally.

#### Additional Information

For many of our repositories, you'll run `npm ci` to install the dependencies and set up the project locally.

When contributing to OpenSauced projects, you can use this command to follow our conventional commits:
From the [npm official docs](https://docs.npmjs.com/cli/v10/commands/npm-ci#description):

> The `npm ci` is a command that installs a project with a clean slate, skipping certain user-oriented features and being more strict than `npm install`.

You can also use the shell commands below to get started once you have forked the repository:

```shell
npm run push
git clone https://github.com/<GITHUB_USERNAME>/<REPO_NAME>.git
cd <REPO_NAME>
npm ci
```

Using the `npm run push` command is an interactive replacement for `git commit`. It enforces the conventional commit specification for writing commit messages, making it easier for developers and maintainers to understand the changes made in a particular commit.
Make sure to replace `<GITHUB_USERNAME>` with your GitHub username.

Assuming you are dealing with code changes and you add them using `git add`, once you are ready to commit, there are two ways we can proceed: `git commit` or `npm run push`. The second method is preferred, as doing a subsequent `git push` and opening a PR would ensure the title conforms to our standards.
### Building

See [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for more examples.
To generate a production-ready version of your code, run:

## Issues
```shell
npm run build
```

If you wish to work on an open issue, please comment on the issue with `.take`, and it will be assigned to you. If an issue is not assigned, it is assumed to be available for anyone to work on. Please assign yourself to an issue before working on it to avoid conflicts.
### Testing

If you contribute to the project for the first time, you can search for issues with `good first issue` or `bug` labels in the repository.
For running the test suite, use the following command:

In case you get stuck, feel free to ask for help in the [Discord](https://discord.gg/U2peSNf23P) server or [GitHub Discussions](https://github.com/orgs/open-sauced/discussions).
```shell
# the tests will run in watch mode by default
npm test
```

Please follow our [code of conduct](./code-of-conduct.md) in all your interactions with the project and its contributors.
Since the tests run in watch mode by default, some users may encounter errors about too many files being open. In this case, it may be beneficial to [install Watchman](https://facebook.github.io/watchman/docs/install.html).

## Triage Team
Check out this course, [Testing JavaScript](https://testingjavascript.com/), for more info on testing React and JavaScript.

The Triage team is inspired by [expressjs/express](https://github.com/expressjs/express/blob/HEAD/Triager-Guide.md). This team exists to create a path for making contributions to this project and open source. All Triage Team members are expected to follow the [Triage Guide](./triage-guide.md).
### Applying Lint Styleguide

> **There are no minimum requirements to become a member of the Triage Team.**
To check the code for formatting and linting errors, run the following command:

For those interested in getting involved in the project or just open source in general and wanting to join the Triage Team, please comment in the `🍕opensauced-contributors-chat` channel on [Discord](https://discord.gg/U2peSNf23P).
```shell
npm run lint
```

## Funding
These errors will also be displayed during development but won't prevent the code from compiling.

OpenSauced is a part of GitHub Sponsors. If you would like to contribute, please note the [sponsor page](https://github.com/sponsors/open-sauced) for details on how funds are distributed. If you have made any contributions to the project directly or indirectly, please consider adding your profile to the [`FUNDING.yml`](https://github.com/open-sauced/.github/blob/main/FUNDING.yml) file.
To fix the formatting and linting errors, run the following command instead:

## Community
```shell
npm run format
```

Do you have questions? Join the conversation in our [Discord](https://discord.gg/U2peSNf23P).
These commands use [ESLint](https://eslint.org/) to check and fix the code.

## Coding Tips
If you forget to run this command, automated PR checks will also run these commands, but the PR will be blocked if there are any errors.

### Coding Tips

- Ask questions if you are stuck.
- Use [CSS variables.](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
- Always use [rel="noreferrer" on all target="\_blank" links](https://web.dev/external-anchors-use-rel-noopener/).

## Community

Do you have questions? Join the conversation in our [Discord](https://discord.gg/U2peSNf23P).

## Triage Team

The Triage team is inspired by [expressjs/express](https://github.com/expressjs/express/blob/HEAD/Triager-Guide.md). This team exists to create a path for making contributions to this project and open source. All Triage Team members are expected to follow the [Triage Guide](./triage-guide.md).

> **There are no minimum requirements to become a member of the Triage Team.**

For those interested in getting involved in the project or just open source in general and wanting to join the Triage Team, please leave a comment in the `🍕opensauced-contributors-chat` channel on [Discord](https://discord.gg/U2peSNf23P).

## Funding

OpenSauced is a part of GitHub Sponsors. If you would like to contribute, please note the [sponsor page](https://github.com/sponsors/open-sauced) for details on how funds are distributed. If you have made any contributions to the project directly or indirectly, please consider adding your profile to the [`FUNDING.yml`](https://github.com/open-sauced/.github/blob/main/FUNDING.yml) file.

## License

By contributing to the OpenSauced project, you agree that your contributions will be licensed
Expand Down
2 changes: 1 addition & 1 deletion docs/welcome/faqs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ You may not see your organization if you are not a "public" member. You can upda

### 2. I get an error when I try to select my team in "Sync your GitHub Team".

If you see your organization but get an error when selecting a team, your organization likely has restricted third-party applications. You can check this if you are an ownder by going to "Your organizations" on GitHub, selecting "Settings", and then "Third-party Access".
If you see your organization but get an error when selecting a team, your organization likely has restricted third-party applications. You can check this if you are an owner by going to "Your organizations" on GitHub, selecting "Settings", and then "Third-party Access".

If you're an **owner** of the repository, you can select "Allow select third-party access" or specifically approve OpenSauced by following the directions in [this guide](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization).

Expand Down
Loading