Skip to main content

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:

  1. Always leave screenshots for visual changes.
  2. Always leave a detailed description in the pull request. Leave nothing ambiguous for the reviewer.
  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.

Issues​

  • If you wish to work on an open issue, please comment on the issue with .take, and it will be assigned to you.

    info

    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.

  • 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 or bug labels in the repository.

    note

    Please only self-assign a good first issue one time.
    Maintainers may remove you from the assignees and not accept your pull request if you choose to proceed.

In case you get stuck, feel free to ask for help in the Community 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.

  1. Fork and clone the repo.

  2. Creating a new branch is a must. Before working on your changes, create a new branch from the default (main, beta, etc.) branch. Name your branch with 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.

  6. Ensure the test suite passes.

  7. Make sure you address any lint warnings.

  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, and all the necessary areas.

    • The title must begin with feat:, fix:, or anything related to your changes.
      TIP: You can follow your chosen option when committing your changes.

    • Unsolicited code is welcomed, but an issue is required to announce your intentions.

    Note for maintainers: All PRs need a label to assist automation. See this guide to determine which labels to use.

warning

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
  • PR form is incomplete, or any section in the form is deleted
  • changes are made directly on the default (main, beta, etc.) branch

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​

  1. Fork the repository you're working on from github/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.

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 than npm 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​

Community​

Do you have questions? Join the conversation in our Community.

info

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.

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.