Skip to content

Latest commit

 

History

History
151 lines (107 loc) · 7.79 KB

CONTRIBUTING.md

File metadata and controls

151 lines (107 loc) · 7.79 KB

Contributing to Twiga 🦒

We welcome contributions of any size and skill level. As an open source project, we believe in giving back to our contributors and are happy to help with guidance on pull requests (PRs), technical writing, and turning any feature idea into a reality.

Tip

For new contributors 🚼: Take a look at first contributions for helpful information on contributing. You can of course ask questions in our Discord.

By contributing you agree to our Code of Conduct.

Merge Policy for Pull Requests

We're using the Gitflow workflow, meaning we don't do PRs for new features directly to the main branch. Any updates to the codebase, whether large or small, are first merged into the development. They're then deployed to our development server (basically our staging area) where we can evaluate if there's any breaking changes. After each milestone we submit a PR from development to main.

Important

Submit your PR against the development branch, not main. We do not accept PRs directly to main.

From Fork to PR with Twiga

Important

Read our Git Guidelines to learn how to develop collaboratively on Twiga like a pro.

To start contributing to Twiga, follow these steps:

  1. Create a fork of this repository and clone it to your local machine

Warning

Remember to uncheck the "Copy the main branch only" so that you get the development branch too

  1. Checkout the development branch: git checkout development
  2. Create your feature branch from the development branch: git checkout -b your-branch-name
  3. Follow the steps in our getting started guide to get the project up and running locally
  4. (Not yet possible) Run the tests to ensure everything is working as expected
  5. Commit your changes: git commit -m "[type]: descriptive commit message"
  6. Push to your remote branch: git push origin your-branch-name
  7. Submit a pull request to the development branch of the original repository

Code Formatting and Linting

Make sure to follow the established coding style guidelines in this project. We believe consistent formatting of the code makes it easier to understand and debug. Therefore, we enforce good formatting conventions using pre-commit in order to automatically run the Python black and ruff formatters on every commit.

Don't worry, you don't need to learn a whole new way of formatting code - it's done for you. Though if you're curious about having these formatters and linters during your development (and not just on commit) we recommend these extensions for VSCode (our preferred editor): Black Formatter and Ruff. When you've completed steps 1-3 in From Fork to PR with Twiga, you can install the dependencies with:

$ uv sync
$ source .venv/bin/activate

Note

For Windows the second command would be .venv\Scripts\activate

Then you can install the pre-commit hooks with:

$ pre-commit install

# output
> pre-commit installed at .git/hooks/pre-commit

An Example of pre-commit in Action

Note

We shamelessly took this example from gpt-engineer. Thanks!

As an introduction of the actual workflow, here is an example of the process you will encounter when you make a commit:

Let's add a file we have modified with some errors, see how the pre-commit hooks run black and fails. black is set to automatically fix the issues it finds:

$ git add random_code_file.py
$ git commit -m "commit message"
black....................................................................Failed
- hook id: black
- files were modified by this hook

reformatted random_code_file.py

All done! ✨ 🍰 ✨
1 file reformatted.

You can see that random_code_file.py is both staged and not staged for commit. This is because black has formatted it and now it is different from the version you have in your working directory. To fix this you can simply run git add random_code_file.py again and now you can commit your changes.

$ git status
On branch pre-commit-setup
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   random_code_file.py

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   random_code_file.py

Now let's add the file again to include the latest commits and see how ruff fails.

$ git add random_code_file.py
$ git commit -m "commit message"
black....................................................................Passed
ruff.....................................................................Failed
- hook id: ruff
- exit code: 1
- files were modified by this hook

Found 2 errors (2 fixed, 0 remaining).

Same as before, you can see that random_code_file.py is both staged and not staged for commit. This is because ruff has formatted it and now it is different from the version you have in your working directory. To fix this you can simply run git add random_code_file.py again and now you can commit your changes.

$ git add random_code_file.py
$ git commit -m "commit message"
black....................................................................Passed
ruff.....................................................................Passed
fix end of files.........................................................Passed
[pre-commit-setup f00c0ce] testing
 1 file changed, 1 insertion(+), 1 deletion(-)

Now your file has been committed and you can push your changes.

At the beginning this might seem like a tedious process (having to add the file again after black and ruff have modified it) but it is actually very useful. It allows you to see what changes black and ruff have made to your files and make sure that they are correct before you commit them.

Note

When pre-commit fails in the build pipeline when submitting a PR you need to run pre-commit run --all-files to have it force format all files, not just the ones you edited since the previous commit.

Sometimes pre-commit will seemingly run successfully, as follows:

black................................................(no files to check)Skipped
ruff.................................................(no files to check)Skipped
check toml...........................................(no files to check)Skipped
check yaml...........................................(no files to check)Skipped
detect private key...................................(no files to check)Skipped
fix end of files.....................................(no files to check)Skipped
trim trailing whitespace.............................(no files to check)Skipped

However, you may see pre-commit fail in the build pipeline upon submitting a PR. The solution to this is to run pre-commit run --all-files to force

Licensing

By contributing to Twiga, you agree that your contributions will be licensed under the License of the project.

Thank you for your interest in contributing to Twiga! We look forward to your contributions.