# Contributing These are the contribution guidelines for openpgp-card-tools. Development takes place at https://codeberg.org/openpgp-card/openpgp-card-tools. Discussion around this project takes place in [`#openpgp-card:matrix.org`] on [Matrix]. ## Writing code This project is written in [Rust] and formatted using the default [`rustfmt`] of the most recent version of Rust. All contributions are linted using [`clippy`] and spell checked using [`codespell`]. The dependencies are linted with [`cargo-deny`]. License identifiers and copyright statements are checked using [`reuse`]. To aide in development, it is encouraged to use the local `.ci/check.sh` script as [git pre-commit hook]: ```shell $ ln -f -s ../../.ci/check.sh .git/hooks/pre-commit ``` ### Changes to structured output The tool supports structured output, such as `JSON` and `YAML`. This output format is versioned, following [semantic versioning], which is exposed by the `schema_version` field. * If a field is added, the minor level is incremented, and patch level is set to zero in all subcommands. The default output version is incremented to the new version. * If a field is removed, the major level is incremented, and minor and patch level are set to zero in all subcommands. The new version is added to the list of available output versions and the new output version is set as the default. * If there are changes to the output with no semantic impact, the patch level is incremented in all subcommands. The default output version is incremented to the new version. When adding a new output version, old versions of the output format remain, until they can not be supported by the tool anymore. Adding a new major level output version increases the minor version level of the project. Removing an output version on the other hand is a breaking change and increases the major version of the project. ## Writing commit messages The commit message style follows [conventional commits]. To aide in development, install [`cocogitto`] and add its [`git-hooks`]: ```shell $ cog install-hook all ``` ## Running tests To run the baseline of tests, all of which will also run in CI, use: ```shell $ ./.ci/check.sh ``` ### Integration tests The integration tests are run using [subplot] and a *virtual smartcard* setup. This test setup is containerized using [podman] to not affect the local system or any local smartcards. To run the test suite, use: ```shell $ ./.ci/check.sh integration ``` ## Creating releases Releases are created by the developers of this project using [`cocogitto`] by running: ```shell $ cog bump --auto ``` The above will automatically: * increase the version based on the conventional commits since the last release * add an entry to `CHANGELOG.md` * create a tag and push the changes to the default branch of the project * build a crate for the release and push it to https://crates.io. ## License All code contributions fall under the terms of the [Apache-2.0] and [MIT]. Configuration file contributions fall under the terms of the [CC0-1.0]. [`#openpgp-card:matrix.org`]: https://matrix.to/#/%23openpgp-card%3Amatrix.org [Matrix]: https://matrix.org [Rust]: https://www.rust-lang.org/ [`rustfmt`]: https://github.com/rust-lang/rustfmt [`clippy`]: https://github.com/rust-lang/rust-clippy [`codespell`]: https://github.com/codespell-project/codespell [`cargo-deny`]: https://github.com/EmbarkStudios/cargo-deny [`reuse`]: https://git.fsfe.org/reuse/tool [git pre-commit hook]: https://man.archlinux.org/man/githooks.5#pre-commit [semantic versioning]: https://semver.org/ [conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/ [subplot]: https://gitlab.com/subplot/subplot/ [podman]: https://github.com/containers/podman [`cocogitto`]: https://github.com/cocogitto/cocogitto [`git-hooks`]: https://man.archlinux.org/man/githooks.5 [Apache-2.0]: ./LICENSES/Apache-2.0.txt [MIT]: ./LICENSES/MIT.txt [CC0-1.0]: ./LICENSES/CC0-1.0.txt