Contributing

These are the contributing guidelines for the alpm project.

Development takes place at https://gitlab.archlinux.org/archlinux/alpm/alpm.

Writing code

This project is written in Rust and formatted using the nightly rustfmt version. The linking is performed via mold.

All contributions are linted using clippy and spell checked using codespell. The dependencies are linted with cargo-deny and unused dependencies are detected using cargo-machete. License identifiers and copyright statements are checked using reuse. Toml files are formatted via [taplo-cli].

Various just targets are used to run checks and tests. shellcheck is used to check the just targets for correctness. In order to review the snapshot changes in tests, you can use cargo-insta.

Code examples in READMEs is tested via tangler. Links in markdown files or doc blocks are tested via lychee.

To get all of the necessary tools installed on Arch Linux, run just install-pacman-dev-packages. To setup Rust for this project run just install-rust-dev-tools. Both can also be done in one fell swoop via just dev-install.

To aide in development, it is encouraged to configure git to follow this project's guidelines:

just configure-git

This just command takes care of a few things:

• Configure git to sign commits for this repository using OpenPGP.
• Install the relevant git pre-commit and git pre-push hooks.
• Install the git prepare-commit-msg hook to automatically add a signoff section to the commit message.

Writing specifications

Specifications for technology of this project are written in markdown documents in the context of a component, that serves as its reference implementation. The specifications are located in the component's resources/specification/ directory and must end on .5.md or .7.md, so that they can be used as section 5 or section 7 man pages, respectively.

Specification versioning

A new specification version must be created, if fields of an existing specification are altered (e.g. a field is removed, added or otherwise changed semantically).

By default, given an example specification named topic and given only one version of topic exists, there would only be a document named topic.7.md. If the need for version two of topic arises, the document is renamed to topicv1.7.md, a new file named topicv2.7.md is used for the new version and a symlink from the generic specification name to the most recent version (here topic.7.md -> topicv2.7.md) is created. Versioned specifications additionally must clearly state the specification version number they are addressing in the NAME and DESCRIPTION section of the document.

New (versions of) specifications must be accompanied by examples and code testing those examples.

The examples and code testing those examples must be kept around for legacy and deprecated specifications to guarantee backwards compatibility.

Writing commit messages

To ensure compatibility and automatic creation of semantic versioning compatible releases the commit message style follows conventional commits.

The commit messages are checked by just run-pre-push-hook via the following tools: cocogitto & committed.

Follow these rules when writing commit messages:

1. The subject line should be capitalized and should not end with a period.

2. The total length of the line should not exceed 72 characters.

3. The commit body should be in the imperative mood.

Here is an example of a good commit message:

feat(parser): Enhance error handling in parser

Improve error handling by adding specific error codes and messages
to make debugging easier and more informative. This update enhances
parsing accuracy and provides more context for handling parsing errors.

Signed-off-by: John Doe <john@archlinux.org>

Merging changes

Changes to the project are proposed and reviewed using merge requests and merged by the developers of this project using fast-forward merges.

Creating releases

Releases are created by the developers of this project using release-plz by running (per package in the workspace):

just prepare-release <package>

Changed files are added in a pull request towards the default branch.

Once the changes are merged to the default branch a tag is created and pushed for the respective package:

just release <package>

The crate is afterwards automatically published on https://crates.io using a pipeline job.

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.

Documentation contributions fall under the terms of the CC-BY-SA-4.0.

Specific license assignments and attribution are handled using REUSE.toml. Individual contributors are all summarized as "ALPM Contributors". For a full list of individual contributors, refer to git log --format="%an <%aE>" | sort -u.