CONTRIBUTING.md

Contributing

Thank you for wanting to contribute to kerblam!

We use issues to track what needs to be done. If you'd like to contribute, pick an issue, comment that you'd like to work on it, and send a pull request when you are done.

Please keep all conversations civil, and do not discriminate anyone for their experience, race or ethnicity, social status, etc.

About the code

Kerblam! is relatively simple. Start reading the main.rs file and follow the imports. Each command is split in its own file. Simple commands are all collected in the other module, since they most often only encompass a function or two.

Kerblam! uses anyhow to handle its Results, as most of the times we just want to end early, without special handling.

Any complex parts of the code should be commented and propely explained. If you are unsure on what something does, and cannot decypher the code, please open an issue - the code probably needs some refactoring if you feel that way.

Code style

Code styling is left to cargo fmt. Please reformat your code before sending a pull request, such as by adding this pre-commit hook:

default_install_hook_types: [pre-commit, commit-msg]
repos:
-   repo: https://github.com/doublify/pre-commit-rust
    rev: v1.0
    hooks:
    -   id: fmt
    -   id: cargo-check
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
    -   id: end-of-file-fixer

Testing

Tests are of two types, integration or unit tests. Both are run with cargo test. Unit tests are your standard doc tests and unit tests, just write them in as you'd normally would.

Kerblam! is also tested against the kerblam-examples examples. Each example is in a directory (e.g. examples/my_example) with a run bash script that runs the example and rolls it back. cargo test checks out the current version of kerblam-examples and runs the run scripts, checking:

• If the run script exited successfully;
• If the number or content of the files in the repo has changed from before the run script was executed.

To add a new example/test, write the example (see the kerblam examples repo), add the run script to the example and add the run_example_named! or run_example_named! macro with the name of the example and if you expect it to succeed or fail, e.g. run_example_named!("my_example", "success").

Testing docker

Since CIs here on github are run in docker containers, there is a problem when trying to test kerblam! on the cloud:

The issue here is that when you run dockerized pipelines, the docker container is connected through a socket to the host container. Therefore, when we bind-mount paths inside the docker container, the bind fails since the host docker daemon does not "see" inside the runtime. It attempts to bind the local (on the host machine of Github) directory but it simply fails since it's not what we want to bind to, resulting in an empty mountpoint.

I think there is not easy solution here.

• @MrHedmad

For this reason, all tests that run Docker at some point are wrapped in the run_ignored_example_named macro instead. To run them locally, use cargo test -- --include-ignored.

These example tests run locally on your machine, so you should make sure that you have properly installed the requirements for kerblam! to run, including both docker and podman executables. If you find that one of these tests has failed, please be sure that it is not due to your specific environment before starting the debug process.

Cutting releases

When we are ready to push a new release, do the following:

• Check if cargo dist needs to be updated (update cargo dist via package manager, then run cargo dist init to apply the new configuration). Commit the change and push.
• Check the changelog. Come up with a new SemVer tag appropriately.
• Edit the changelog with the new tag, replacing the [Unreleased] section to [v0.0.0] - YYYY-MM-DD.
• Update cargo.toml with the new tag, commit the change and push.
• To trigger a release, push a tag to the main branch with the version that needs to be release. This triggers cargo-dist to build the binaries and installers and upload them to the release.
  • For example: git tag v0.0.0 && git push --tags
• To publish on crates.io, use cargo publish after triggering cargo-dist.
  • Wait until the cargo dist action on Github has concluded before pushing to crates.io.

And you're done! You might want to edit the release made automatically by cargo-dist with more information, perhaps by adding a changelog.

Contributions

Currently, the Kerblam! maintainer is MrHedmad. There are no other maintainers. All contributions are listed below by the @all-contributors bot.

Significant contributions will be recognized by a spot in the maintainers list, at the discretion of other maintainers.

All contributors

Thank you to all of these wonderful people! Emojis reflect the specific contribution of that user. See the emoji key (or you can hover with your mouse over each emoji to see its meaning).

Luca "Hedmad" Visentin 💻 📖 🤔 📆 ✅

Federico Alessandro Ruffinatti 🐛 🎨