CONTRIBUTING.md

Contributing

Hi there! First off, we're thrilled 🤩 you want contribute to this project!

First time contributor to a GitHub project? If you could use some help getting started, take a look at this quick and easy guide. 💜

Briefly: Submitting a Pull Request (Pr)

See also: CODE_OF_CONDUCT.md

This repository uses a fully automated continuous linting (CL), integration testing (CI), and deployment (CD) projector-based pipeline for integrating PRs and publishing releases. The neat thing about a fully automated pipeline is that anyone anywhere can make a contribution quickly and with minimal tedium.

This repository makes extensive use of debug. Should you wish to view all possible debugging output, export DEBUG='*,*:*'.

The ideal contributor flow is as follows:

1. Fork this repository and clone it locally.
   • If there is a custom Docker image available for this project and you're comfortable with Docker, consider using it instead.
2. Configure and install dependencies with npm ci.
   • You use npm ci here instead of npm install to prevent unnecessary updates to package.json and package-lock.json, but if it makes more sense to use npm install feel free to use that instead.
   • If .env.example exists, consider copying it to .env and configuring sensible defaults.
3. Before making any changes, ensure all unit tests are passing with npm run test.
4. (optional but recommended) Create a new branch, usually off main.
   • Example: git checkout -b contrib-feature-1.
5. Make your changes and commit. Your work will be checked as you commit; any problems will abort the commit/push attempt.
   • Ensure any new tests still pass even when the DEBUG environment variable is defined.
6. Push your commits to your fork and, when you're ready, fearlessly submit your PR! Your changes will be tested in our CI pipeline.
7. Pat yourself on the back! Your hard work is well on its way to being reviewed and, if everything looks good, merged and released 🚀

Additionally, there are a few things you can do to greatly increase the likelihood your PR passes review:

• Do open an issue and discuss your proposed changes (to prevent wasting your valuable time, e.g. maybe we're already working on a fix!), and search to see if there are any existing issues related to your concerns.
• Do practice atomic committing.
• Do not reduce code coverage (codecov checks are performed during CI).
• Do follow convention when coming up with your commit messages.
• Do not circumvent CL, i.e. automated pre-commit linting, formatting, and unit testing.
• Do ensure README.md and other documentation that isn't autogenerated is kept consistent with your changes.
• Do not create a PR to introduce purely cosmetic commits.
  • Code de-duplication and other potential optimizations we do not consider purely cosmetic 🙂
• Do keep your PR as narrow and focused as possible.
  • If you ran npm install instead of npm ci and it updated package.json or package-lock.json and those updates have nothing to do with your PR (e.g. random nested deps were updated), do not stage changes to those files.
  • If there are multiple related changes to be made but (1) they do not immediately depend on one another or (2) one implements extended/alternative functionality based on the other, consider submitting them as separate PRs instead.

At this point, you're ready to create your PR and ✨ contribute ✨!