docs/docs/contributing.md

Contributing

Tip

This document provides a high-level overview of contributing to our projects. Check with each project's documentation for more specific or supplemental instructions, if needed.

Please ensure all pull requests and contributions comply with the Developer Certificate of Origin.

Note

All contributions to our projects will be licensed under our global license

Setting Up Your Code

First, fork the repository to your own account. Then use git clone <url> to bring your forked repository down to your local machine (remember to get the URL for your repository, not the original). Optionally, use git remote add upstream <url> to add the original repository as the upstream (this is helpful for keeping your fork up-to-date).

Claiming an Issue

All of our issues are open to contributors! If you see an open issue you would like to work on, please comment on the issue so we may assign it to you.

Note

Assigned issues that have not had any activity in a week will be unassigned.

If an issue is already assigned, that means someone has expressed interest in working on it. We encourage you to reach out to them and collaborate on a PR together!

We use special labels to help categorise issues. Feel free to browse our breakdown of the labels.

Working on your issue

Before starting work, we highly recommend ensuring that your forked version is up to date. If you set the upstream as mentioned in Setting Up Your Code, run these commands in your terminal (with the terminal pointed at the root directory of your local files):

• git fetch upstream - this gets the current state of the original repo, without pulling down the changes to your local machine.
• git reset --hard upstream/main - this resets the state of your local files to match the current state of the original repo.
• git push -f - this forces the changes to your forked repo (thus making it match the original)

Note

You will lose any changes you are currently working on. Do this with care.

Next, use git checkout -b <branchname> to create a new branch for your work. It's always a good idea to avoid committing changes directly to your main branch - this keeps it clean and avoids errors when updating (above).

Branch names should follow a convention of scope/description where:

• scope is the nature of the changes (eg. feat for a new feature, or docs for documentation update). This should match the scope of the related issue.
• description is a brief description of your changes, such as update-contribs for updating the contributing guidelines.

Now you are free to work on your code! When you are satisfied with your changes, you can commit them with git commit -s -m "message", where:

• -s flag signs the commit, to verify the connection with your GitHub account.
• -m flag sets up the commit message.
• message is the commit message: a brief (50 character max) message describing what the commit changes.

Tip

If you aren't sure which package manager to use, you can reach out to us in our chat server.

Installing Packages

Use pnpm install to install all current packages.

Adding Packages

pnpm install will allow you to add a new package.

When adding a new package, you should use the --save-exact flag to pin the package version. The CI will check for unpinned versions when you open a PR.

If the package is only for development (working on the project), and not needed for production (running the project), you should also use the --save-dev flag to add the package to the devDependencies section of the package.json file.

For example:

pnpm i --save-dev --save-exact @types/naomi # Adds a dev dependency
pnpm i --save-exact naomi # Adds a production dependency

Oops! I used npm when I should have used pnpm

No worries! A quick note that if you ran npm install or npm ci, then pnpm will ignore the installed packages. You will need to run the following commands to get back in sync:

rm -rf package-lock.json node_modules
pnpm install

Testing Changes

Note

Make sure to follow the steps above to check which package manager the project uses, and use the appropriate commands.

Many of our projects will have continuous integration (CI) checks that run on a pull request. To ensure your changes will pass, you can often test these locally.

If the project has a package.json file, check for the following entries in the scripts property:

• build - Running pnpm run build will confirm that a project successfully compiles. This is common in our TypeScript projects.
• lint - Running pnpm run lint will ensure that the code style is correct.
• start - Running pnpm start will confirm that the project boots up successfully.
• test - Running pnpm test will ensure that the unit and functional tests all pass.

You can also check the .github/workflows directory for .yml files. These files will describe the actual CI checks that run on your pull request.

Ensuring these checks pass before submitting a pull request will streamline our review process.

Submitting a Pull Request

Once you have all of your changes made and committed, you can push them to your forked repository! Use git push -u origin <branchname>, where:

• -u tells git to set the upstream (see below)
• origin tells git to push to your fork
• branchname tells git to push to a branch - this MUST match the name of the branch you created locally.

Note

By setting the upstream, any subsequent push commands can be done with git push, and it will be pushed to the same branch.

Now you can open the pull request! You should see a quick option to do so appear at the top of your repository on GitHub. Click the "Pull Request" button to have GitHub automatically set up the pull request.

First, change the title of the pull request to match your branch name (following the conventions above!). Then, follow the instructions in the preset Pull Request template (make sure to complete any steps listed!).

Congratulations! You've submitted your first pull request! We will review it as quickly as possible, so keep an eye out for approvals (or requested changes).

Pull Request Reviews

All pull requests require a review before being merged. Most reviews will come from Naomi, but some projects may have additional staff who can submit reviews.

If your pull request is approved, it will be merged and deployed depending on the project's deployment schedule and pipeline.

If your pull request requires additional changes or information, we ask that you apply the changes promptly. Contributions with outstanding change requests that receive no activity within a week will be closed as stale.

Other Contributions

If you aren't comfortable with the codebase, or would like to contribute in other ways, we have options for that!

• Documentation Updates: You are always welcome to update our documentation (like this file!) if you see any typos or anything that can be clarified.
• Feature Requests: If you have ideas for new features or improvements, feel free to open an issue!
• Bug Reports: We rely on our users to help identify bugs - if you see something wrong, please let us know with an issue!

Holopin Badges

Contributors are eligible to receive digital Holopin badges for their contributions to our projects. To claim your badge, fill out the template in our Discord community!