Skip to content

Latest commit

 

History

History
102 lines (63 loc) · 4.9 KB

CONTRIBUTING.md

File metadata and controls

102 lines (63 loc) · 4.9 KB
Raw

🧑‍💻 Contributing to matcha

Welcome to matcha 🍵! We're excited that you're thinking about contributing to our project.

🔥 Quicklinks

🎬 Getting started

Contributions are made to this project using Issues and Pull Request (PRs). Before creating your own, search for existing Issues and PRs - as I'm sure you're aware, this removes duplication and makes everyone's life easier!

😭 Issues

Issues should be used to report bugs with matcha, proposing new features before a PR is raised, and to request new features. We're making use of templates to make this process easier for you and consistent for everyone - this will appear when you create an issue.

If you find an issue that has already been reported by another good samaritan, then please add your own reproduction information to the existing issue rather than creating a new one. Reacting to issues can also help our maintainers understand that the issue is affecting more than one reporter.

🎫 Pull Requests

Pull Requests (PRs) are how contributions are made to matcha and are always welcome.

The preferred way to contribute to matcha is to fork the main repository on Github and then submit a pull request.

🖥️ Getting setup locally

Here, we'll explain to get setup locally with matcha and how to set up your git repository:

  1. If you don't already have one, create an account on Github.

  2. Fork the repository by clicking on the 'fork' button near the top of the page. What this will do is create a copy of the matcha repository under your Github account. See here for a guide on how to fork a repository.

  3. Clone this forked version of matcha to your local disk:

git clone git@github.com:<your_username>/matcha.git
cd matcha
  1. Add the upstream remote. Adding this means you can keep your repository sync'd with the latest changes to the main repository:
git remote add upstream git@github.com:fuzzylabs/matcha.git
  1. Check that these remote aliases are correctly configured by running: git remote -v, this should show the following:
origin  git@github.com:<your_username>/matcha.git (fetch)
origin  git@github.com:<your_username>/matcha.git (push)
upstream        git@github.com:fuzzylabs/matcha.git (fetch)
upstream        git@github.com:fuzzylabs/matcha.git (push)

Now you have git properly configured, you can install the development dependencies which are described in DEVELOPMENT. Once the development environment is setup, you can start making changes by following these steps:

  1. Sync your main branch with the upstream/main branch:
git checkout main
git fetch upstream
git merge upstream/main
  1. Create your feature branch which will contain your development changes:
git checkout -b <your_feature>

and you can now start making changes! We're sure that you don't need reminding but it's good practise to never work on the main branch and to always use a feature branch. The DEVELOPMENT guide tells you how to run tests.

  1. Develop your feature on your computer and when you're done editing, add the changed files to git and then commit:
git add <modified_files>
git commit -m '<a meaningful commit message>'

Once committed, push your changes to your Github account:

git push -u origin <your_feature>
  1. Once you're finished and ready to make a pull request to the main repository, then follow the steps below

🤔 Making a pull request

Before a PR can be merged, two core developers need to approve it. It may be the case that you have an incomplete contribution, where you're expecting to do more work before receiving a full review, and these should have the prefix [WIP] - this will indicate to everyone that it is a work in progress ticket and will avoid duplicated work. These types of PRs often benefit from including a task list in the PR description.

It's important to do the following, and the PR template that you'll see will ask you explicitly:

  • Give your pull request a helpful title which summarizes what your contribution does.

  • Make sure your code passes the tests. At the moment, running the whole test suite doesn't take a long time so we advice doing that with pytest (see the DEVELOPMENT guide).

  • Your PR will also be checked for spelling errors in the CI by the typos crate. If a false positive is raised by the checker, consider adding it to the .typos.toml file in the root of the project.

  • Ensure that your code is documented and commented, and that the documentation renders properly.