gman/CONTRIBUTING.md

Contributing

Contributors are very welcome! No contribution is too small and all contributions are valued.

Rust

You'll need to have the stable Rust toolchain installed in order to develop GMan.

The Rust toolchain (stable) can be installed via rustup using the following command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

This will install rustup, rustc and cargo. For more information, refer to the official Rust installation documentation.

Commitizen

Commitizen is a nifty tool that helps us write better commit messages. It ensures that our commits have a consistent style and makes it easier to generate CHANGELOGS. Additionally, Commitizen is used to run pre-commit checks to enforce style constraints.

To install commitizen and the pre-commit prerequisite, run the following command:

python3 -m pip install commitizen pre-commit

Commitizen Quick Guide

To see an example commit to get an idea for the Commitizen style, run:

cz example

To see the allowed types of commits and their descriptions, run:

cz info

If you'd like to create a commit using Commitizen with an interactive prompt to help you get comfortable with the style, use:

cz commit

Setup workspace

1. Clone this repo
2. Run cargo test to set up hooks
3. Make changes
4. Run the application using just run or just run
   • Install just (cargo install just) if you haven't already to use the justfile in this project.
5. Commit changes. This will trigger pre-commit hooks that will run format, test and lint. If there are errors or warnings from Clippy, please fix them.
6. Push your code to a new branch named after the feature/bug/etc. you're adding. This will trigger pre-push hooks that will run lint and test.
7. Create a PR

CI/CD Testing with Act

If you also are planning on testing out your changes before pushing them with Act, you will need to set up act, docker, and configure your local system to run different architectures:

1. Install docker by following the instructions on the official Docker installation page.
2. Install act by following the instructions on the official Act installation page.
3. Install binfmt on your system once so that act can run the correct architecture for the CI/CD workflows. You can do this by running:

   sudo docker run --rm --privileged tonistiigi/binfmt --install all
   

Then, you can run workflows locally without having to commit and see if the GitHub action passes or fails.

For example: To test the release.yml workflow locally, you can run:

act -W .github/workflows/release.yml --input_type bump=minor

Questions? Reach out to me!

If you encounter any questions while developing G-Man, please don't hesitate to reach out to me at alex.j.tusa@gmail.com. I'm happy to help contributors in any way I can, regardless of if they're new or experienced!