diff --git a/docs/contributing/introduction-to-contributing.md b/docs/contributing/introduction-to-contributing.md index 0684d6bb..1c1daf22 100644 --- a/docs/contributing/introduction-to-contributing.md +++ b/docs/contributing/introduction-to-contributing.md @@ -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//.git -cd -npm ci -``` - -Make sure to replace `` 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. @@ -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.
**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.
**_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 @@ -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//.git +cd +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 `` 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 diff --git a/docs/welcome/faqs.md b/docs/welcome/faqs.md index 98770cfe..c44b83d1 100644 --- a/docs/welcome/faqs.md +++ b/docs/welcome/faqs.md @@ -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).