Skip to content

Commit

Permalink
docs: Reorganize Subsections in the Intro to Contributing (#233)
Browse files Browse the repository at this point in the history 
* fix: items format in sidebars.js

* Fix typo in faqs.md

* docs(introduction-to-contributing.md): reorganize sections for better flow and clarity

* docs(introduction-to-contributing.md): add h2 of Getting Started

* docs(introduction-to-contributing.md): adjust headings level in Getting Started section

* docs: rename title from Setup to Setting Up Projects Locally"

* docs(introduction-to-contributing.md): adjust wordings in the Triage Team section

* docs: adjust wordings in the Commit section

* docs: add short description of npm-ci

* Revert "fix: items format in sidebars.js"

This reverts commit cfa940c.

* docs: change branch naming example

* docs: add tips for PR title naming
  • Loading branch information
@adiati98
adiati98 authored Dec 14, 2023
1 parent d72032f commit 935e09a
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 73 deletions.
150 changes: 78 additions & 72 deletions docs/contributing/introduction-to-contributing.md
View file
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

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
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

0 comments on commit 935e09a

Please sign in to comment.