Skip to main content

Contributing

Phase 1 - Up & Running​

Before getting started, it is important to have a basic understanding of how to contribute to open-source. The main question to answer here is: "If I don't have write permissions to this repository, how do I contribute?"

1a Create Your Fork​

With the assumption that you are new to the project and do not have write permissions to this repository, you will need to make a copy of it which is your own by forking it. This can be done by clicking the "Fork" button in the top right of the repository homepage.

Github's official documentation: Fork a repository

1b Clone Your Fork​

Next simply git clone into your local machine using

Github's official documentation: Cloning a repository

1c Install Dependencies​

  • Confirm you have Node version 20.10.0 and NPM version 10.2.3 installed and active
  • npm ci from the root directory of the project
  • npm run dev from the root directory to confirm the project is installed and runs successfully

1d Recommendations​

IDE: VS Code

Plugins:

Phase 2 - Development​

npm run dev runs the src/* vitest test suite in watch mode which enables you to develop and test in parallel.

To add a new util function to the project, simply run npm run init [myUtil] with [myUtil] being the name of the function you are wanting to create. This will add all the default directory and files you need to get up and running.

❗ IMPORTANT ❗Do not edit any *.d.ts file - these will be automatically generated or updated for you at build time.

From there it is all code implementation and test coverage - feel free to follow the existing utils as a guide on how to export and test the code. Below is a link to the tool responsible for running both the npm run dev & npm run test commands:

Vitest

Phase 3 - Documenting​

Make your utility function known to the world! Explain why and how to use it within the site directory. It is a simple Docusaurus markdown site which is deployed via Vercel to https://www.communitils.com/.

Follow this template on how to document your function while staying consistent with the rest of the project.

Github's official documentation: Markdown Reference

After code is implemented, tested and documented this will lead to an approval and be considered code complete. Once code complete, it will be merged into main and planned for the next npm publish release.

Phase 4 - Publishing​

Before shipping to production, we must first update the package.json version and run npm i to make sure the package-lock file also gets the new version.

To publish code to npm and deploy the docs site to production there are 2 Github actions that run every time a git tag is pushed to the repository:

The git tag and Github release name must match the exact version specified in the package.json file prefixed with "v".

Examples: v0.5.0, v1.2.3, etc...

Github's official documentation: Managing releases in a repository