Skip to content

Contributing

Guidelines

These are the contributing guidelines for the alpm project.

Development takes place at Archlinux alpm.

Back to: ALPM

Writing Code⚓︎

Writing Code

  • This project is written in Rust and formatted using the nightly rustfmt version.

  • 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:

Localization and Translations⚓︎

Localization and Translations

This project supports localization and translations of its user-facing strings.

Translation Key Structure⚓︎

Translation Key Structure

Translation keys use a hierarchical kebab-case naming scheme that maps the code base structure:

{module}-{group}-{key}
  • module typically mirrors the Rust file that contains the translation usage.
  • group is optional and highlights that a subset of keys inside a module refers to the same feature.
  • key pinpoints the specific translation.

Adding Translations⚓︎

Adding Translations

Join our translation efforts at Weblate!

When adding new translation keys or changing existing ones, follow these rules:

  1. Add or change keys only in the English .ftl files in locales/ and commit them here. Weblate will automatically pick up new keys after a push.

  2. Do not edit non-English translations directly in the repository. Instead, update them via Weblate and a respective translation merge request will be created in GitLab.

Also, follow these conventions when adding or updating translation keys:

  1. Use lowercase ASCII letters with hyphens as separators. Avoid other punctuation.
  2. Keep related keys under a shared {module}-{group} prefix to make their relationship obvious.
  3. Pick descriptive names that clarify what the text is used for and where it sits within the hierarchy.

Some examples are error-io-write-archive and cli-format-pretty-help.

Testing⚓︎

Testing

We run [nextest] for fast execution of unit and integration tests.

  • just test calls cargo nextest as well as just test-docs, which runs the doc tests as nextest isn't capable of doing that yet.

The just containerized-integration-tests recipe executes all tests that are made available by a _containerized-integration-test feature and are located in an integration test module named containerized.

With the help of a custom target runner, these tests are executed in a containerized environment using [podman].

The just virtualized-integration-tests recipe executes all tests that are made available by a _virtualized-integration-test feature and are located in an integration test module named virtualized.

Different from the containerized-integration-tests recipe, this test target concerns itself with tests that are not run in a container, but must be run on bare metal or in a virtual machine.

For parameterized tests, we utilize rstest. This is encouraged, but don't go overboard when writing your own tests.

As a rough guideline, if your parameterization results in if checks inside the test, consider creating a dedicated test function for that case.

Code Coverage Reports⚓︎

Code Coverage Reports

Code coverage for unit tests, doc tests and integration tests is calculated using [cargo-llvm-cov].

Each test recipe (e.g. just test, just test-docs, just containerized-integration-tests) can be instructed to generate coverage data.

The payloads (e.g. examples and tests) are compiled while exposing the environment variables set by cargo-llvm-cov show-env which results in them including coverage instrumentation.

In a second step, the just create-coverage-report command creates a cobertura code coverage report from all existing coverage data in $CARGO_TARGET_DIR/llvm-cov/, utilizing the [llvm-tools-preview] component.

When calling just create-coverage-report with-docs, doc tests are considered as well. However, this is still an unstable nightly-only feature and it always requires to generate coverage data for unit tests (just test) and doc tests (just test-docs) first.

Continuous Integration⚓︎

Continuous Integration

  • This project's checks and tests are executed in a continuous integration environment based on Arch Linux.

  • If the CI environment variable is set (this is usually the case e.g. in GitLab CI pipelines), our custom target runner script will automatically select the Arch Linux GitLab container registry instead of the default container registry to circumvent running into rate limiting.

Writing Specifications⚓︎

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⚓︎

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⚓︎

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.

  4. Avoid using the crate name as the commit scope. (e.g. feat(alpm-types)) The changelog entries will be generated for the associated crate accordingly using [release-plz] and [git-cliff].

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⚓︎

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⚓︎

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⚓︎

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.

Back to: ALPM