Introduction to Contributing
Contributions are always welcome, no matter how large or small. Before contributing, please read the Code of Conduct and follow the directions below:
Recommended Communication Styleβ
- Always leave screenshots for visual changes.
- Always leave a detailed description in the pull request. Leave nothing ambiguous for the reviewer.
- Always review your code first. Run the project locally and test it before requesting a review.
- 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.
Issuesβ
If you wish to work on an open issue, please comment on the issue with
.take
, and it will be assigned to you.infoIf 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.
Issues with the
needs triage
label are unavailable to.take
until they are triaged and the label is removed. Feel free to check on the issue regularly if you want to work on it.If you contribute to the project for the first time, you can search for issues with
good first issue
orbug
labels in the repository.notePlease only self-assign a
good first issue
one time.
In case you get stuck, feel free to ask for help in the Discord server or GitHub Discussions.
Please follow our Code of Conduct in all your interactions with the project and its contributors.
Commitsβ
When contributing to OpenSauced projects, use this command to follow our conventional commits:
npm run push
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.
After running this command, you can push your changes to the remote repo.
See Conventional Commits for more examples.
Pull Requests (PR)β
We actively welcome your pull requests. However, you must ensure that you are assigned to an existing issue before working on changes, and you need to link your work to the issue in your PR form.
Fork the repo and create your branch from the default branch.
Name your branch to something descriptive of your work, i.e.,
add-navbar
orfix/broken-links
.If you've added code that should be tested, add tests.
If you've changed APIs, update the documentation.
If you make visual changes, screenshots are required.
Ensure the test suite passes.
Make sure you address any lint warnings.
If you improve the existing code, please let us know in your PR description.
Completing the PR form is required. Make sure to fill in the PR title, description, link to an issue, and all the necessary areas.
The title must begin with "feat:", "fix:", or anything related to your changes.
Tips: You can follow your chosen option when committing your changes.Unsolicited code is welcomed, but an issue is required to announce your intentions.
β οΈ PRs will be marked as invalid and may be closed if:
- the issue is not assigned to the contributor who opened the PR
- no issue is linked to the PR
IMPORTANT:
Please do not DM Maintainers or contact them outside of GitHub if you want a PR Review. If you haven't received a review within a week, please tag them in the PR comments to ask for an estimated time of review.
Note for maintainers: All PRs need a label to assist automation. See this guide to determine which labels to use.
PR Validationβ
Examples of valid PR titles:
- fix: Correct typo.
- feat: Add support for Node 12.
- refactor!: Drop support for Node 6.
Note: For any breaking changes, you have to use the !
syntax.
Work in Progressβ
GitHub supports draft pull requests, which will disable the merge button until the PR is marked as ready for merge.
Additional Resourcesβ
Getting Startedβ
Setting Up Projects Locallyβ
- Fork the repository you're working on from github/open-sauced to your own GitHub account.
- Clone the forked repository to your local machine.
- 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.
From the npm official docs:
The
npm ci
is a command that installs a project with a clean slate, skipping certain user-oriented features and being more strict thannpm install
.
You can also use the shell commands below to get started once you have forked the repository:
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:
npm run build
Testingβ
For running the test suite, use the following command:
# the tests will run in watch mode by default
npm test
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.
Check out this course, Testing JavaScript, for more info on testing React and JavaScript.
Applying Lint Styleguideβ
To check the code for formatting and linting errors, run the following command:
npm run lint
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:
npm run format
These commands use ESLint to check and fix the code.
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.
- Always use rel="noreferrer" on all target="_blank" links.
Communityβ
Do you have questions? Join the conversation in our Discord.
Triage Teamβ
The Triage team is inspired by expressjs/express. 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.
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.
Fundingβ
OpenSauced is a part of GitHub Sponsors. If you would like to contribute, please note the sponsor page 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
file.
Licenseβ
By contributing to the OpenSauced project, you agree that your contributions will be licensed
by a specific License. You can find this information in the LICENSE
file of the repo you are contributing to.