Skip to content

Latest commit

 

History

History
271 lines (180 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

271 lines (180 loc) · 10.3 KB
Raw

🍻 Contributing

Thank you for considering contributing to this project!


Before you doing so, please read the following simple steps on how to contribute. This will make life easier and help to avoid wasting time on things, which are not requested. ⏳


📑 Get Familiar With The Project And It's Tools

Check out in detail the:

  • README.md, especially the Usage and API sections

  • package.json for NPM scripts, additional configs, and dependencies

  • src directory for sources, structure, and naming conventions

  • *.js files for coding style and commenting style, and get familiar with StandardJS

  • tests directory for tests, the test style, the test process, and get familiar with Jest

  • scripts directory and the project's root for tools, scripts, tasks, configs, and get familiar with Gulp

  • Issues and Commits for the release workflow and get familiar with commitizen commit message conventions


💡 Discuss The Change

  • Search open and closed issues first before submitting a new one. Existing issues often contain workarounds, resolutions, or progress updates.

  • If you couldn't find the relevant issue, open a New Issue by choosing the appropriate and relevant issue type.

  • Follow the guide of the issue type you chose and describe your contribution in detail and what change would you like to make.

  • Adhere to the Code of Conduct for a more welcoming environment, productive contribution, and smoother experience.

  • Wait for feedback before continuing to the next steps. However, if the issue is clear (a tiny bug, a build, or a doc typo, etc) and the fix is simple, you can continue and fix it.


🛠️ Fixing Issues

  • Fork the project, then:

    • Clone your own fork:

      git clone https://github.com/<your-username>/path.git

    • Navigate into the project's directory, configure the remote, then install the dependencies:

      git remote add upstream https://github.com/nodewell/path.git
npm install

    • If you cloned a while ago, get the latest changes from upstream, then update the dependencies:

      git checkout master && git pull upstream master
rm -rf node_modules && npm install

  • Create a new branch for your change using commitizen-style naming convention in dash-case:

    • Use this general template for your branch names, notice <scope> is optional (omit ONLY, when you're working on a larger, or multifaceted change with several scopes):

      git checkout -b <type>-<scope?>-<subject>

    • General examples:

      # bugfix:
git checkout -b fix-scope-short-imperative-tense-title

# feature:
git checkout -b feat-scope-short-imperative-tense-title

# feature without scope (omitted):
git checkout -b feat-short-imperative-tense-title

# doc change:
git checkout -b docs-scope-short-imperative-tense-title

    • Specific examples:

      # bugfix:
git checkout -b fix-homepage-fix-hero-typos     

# feature:
git checkout -b feat-backend-add-image-resizing

# feature without scope (omitted):
git checkout -b feat-add-initial-image-upload

# test:
git checkout -b test-validation-add-middle-name-tests

# test without scope (omitted):
git checkout -b test-add-initial-form-tests

  • Commit your changes in that branch in logical chunks:

    • Make sure to adhere to commitizen conventions, otherwise your code is unlikely to be merged into the main project. For your own convenience, optionally you can run this NPM script to help with your commit messages:

      npx git-cz

    • For the main change (when you're done with your fix/feature/test/etc.) use the proper commit message format:

      <type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<breaking change>
<BLANK LINE>
<footer>

      • Example:

        fix(validator): fix middle name validation

Fix the broken middle name validation, when choosing `detailed` name option for first, middle, and last name. Also add a boolean toggle for middle name validaton.

Closes #42

    • For intermediate/small changes (when you're not done yet with the particular fix/feature/test/etc., but you need to commit some changes) use the shorter, simpler subject-body format:

      <subject>
<BLANK LINE>
<body>

      • Example:

        add initial dirs and files

Add an initial .gitattributes file with initial, default content.
Also add lib/ and src/ dirs with .gitkeep files.

    • Add yourself to the array of contributors (create it if it doesn't exist) in package.json:

      "contributors": [
  "Your Name <your@email.com> (www.yoursite.com)"
],

  • Ensure consistency and quality throughout all changes:

    • Follow and adhere to StandardJS coding style and make sure the tests run without errors by running:

      npm run check

    • Use Git's interactive rebase feature to tidy up your commits before making them public:

      git rebase --interactive [base]

  • Then finally:

    • Locally merge (or rebase) the upstream branch into your branch:

      git pull [--rebase] upstream master

    • Push your branch up to your fork:

      git push origin <your-branch-name>

🏁 Submit A Pull Request

  • Open a pull request, follow the descriptions, fill out the sections accordingly, and reference the initial issue in the pull request message (e.g.: fixes #42) - if exists, so everybody will know what is fixed/improved.

  • For ambitious changes, open a Pull Request as soon as possible with the [WIP] prefix in the title, in order to get feedback and help from the community.

  • If it makes sense, add screenshots, gifs, etc., so it will be easier to see what is going on.

  • Allow the project owners to make changes to your pull request branch, so we can rebase it and make some minor changes if necessary (all changes we make will be done in new commit and we'll ask for your approval before merging them).

  • Make sure GitHub Actions runs all tests without errors on your own branch (if GitHub Actions errors out on your own branch, fix the issues, then commit and push again until all tests run without errors).

  • IMPORTANT: by submitting a change, you agree to allow the project owners to license your work under the terms of:


👍 Wait For Feedback

Your contribution will be reviewed before accepted. You may get feedback about what should be changed/fixed in your contribution.



💕 Thank You!

...for your time and contribution. ❤️