managarr/CONTRIBUTING.md

Contributing

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

License and Attribution

If you plan on contributing to the base project, no attribution is needed! Feel free to proceed to the next steps.

Otherwise, below are key points to understand from the Managarr License, Version 1.0:

1. Non-Commercial Use:

   • Managarr is licensed solely for non-commercial purposes. Any commercial use of Managarr (e.g., selling or offering as a paid service) requires separate permission.

2. Attribution when Forking and Redistributing Without Contributing back to Main Project:

   • If you fork the project and distribute it separately (e.g., publish or publicly host it independently from the original project), you are required to provide attribution.
   • You may credit the original author by using any of the following phrasing:
     • "Thanks to Alexander J. Clarke (Dark-Alex-17) for creating the original Managarr project!"
     • "Forked from the Managarr project, created by Alexander J. Clarke (Dark-Alex-17)"
     • "This software is based on the original Managarr project by Alexander J. Clarke (Dark-Alex-17)"
     • "Inspired by Alexander J. Clarke (Dark-Alex-17)'s Managarr project"
   • If changes are made to the base Managarr project, please note those modifications and provide the new attribution accordingly.

Rust

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

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

Authorship Policy

All code in this repository is written and reviewed by humans. AI-generated code (e.g., Copilot, ChatGPT, Claude, etc.) is not permitted unless explicitly disclosed and approved.

Submissions must certify that the contributor understands and can maintain the code they submit.

Questions? Reach out to me!

If you encounter any questions while developing Managarr, please don't hesitate to reach out to me at alex.j.tusa@gmail.com. I'm happy to help contributors, new and experienced in any way I can!