Thank you for your interest in contributing to Alacritty!
Table of Contents:
Feature requests should be reported in the Alacritty issue tracker. To reduce the number of duplicates, please make sure to check the existing enhancement and missing feature issues.
Bug reports should be reported in the Alacritty issue tracker.
If a bug was not present in a previous version of Alacritty, providing the exact commit which introduced the regression helps out a lot.
All patches have to be sent on Github as pull requests.
If you are looking for a place to start contributing to Alacritty, take a look at the help wanted and easy issues.
You can find the minimum supported Rust version in Alacritty's manifest file (cat alacritty/Cargo.toml | grep "rust-version"
). Alacritty must always build with the MSRV and bumping it should be avoided if possible.
Since alacritty_terminal
's version always tracks the next release, make sure that the version is bumped according to semver when necessary.
To make sure no regressions were introduced, all tests should be run before sending a pull request. The following command can be run to test Alacritty:
cargo test
Additionally if there‘s any functionality included which would lend itself to additional testing, new tests should be added. These can either be in the form of Rust tests using the #[test]
annotation, or Alacritty’s ref tests.
To record a new ref test, a release version of the patched binary should be created and run with the --ref-test
flag. After closing the Alacritty window, or killing it (exit
and ^D
do not work), some new files should have been generated in the working directory. Those can then be copied to the ./tests/ref/NEW_TEST_NAME
directory and the test can be enabled by editing the ref_tests!
macro in the ./tests/ref.rs
file. When fixing a bug, it should be checked that the ref test does not complete correctly with the unpatched version, to make sure the test case is covered properly.
If changes could affect throughput or latency of Alacritty, these aspects should be benchmarked to prevent potential regressions. Since there are often big performance differences between Rust‘s nightly releases, it’s advised to perform these tests on the latest Rust stable release.
Alacritty mainly uses the vtebench tool for testing Alacritty's performance. Instructions on how to use it can be found in its README.
Latency is another important factor for Alacritty. On X11, Windows, and macOS the typometer tool allows measuring keyboard latency.
Code should be documented where appropriate. The existing code can be used as a guidance here and the general rustfmt
rules can be followed for formatting.
If any change has been made to the config.rs
file, it should also be documented in the man pages.
Changes compared to the latest Alacritty release which have a direct effect on the user (opposed to things like code refactorings or documentation/tests) additionally need to be documented in the CHANGELOG.md
. When a notable change is made to alacritty_terminal
, it should be documented in alacritty_terminal/CHANGELOG.md
as well. The existing entries should be used as a style guideline. The change log should be used to document changes from a user-perspective, instead of explaining the technical background (like commit messages) More information about Alacritty's change log format can be found here.
All Alacritty changes are automatically verified by CI to conform to its rustfmt guidelines. If a CI build is failing because of formatting issues, you can install rustfmt using rustup component add rustfmt
and then format all code using cargo fmt
.
Unless otherwise specified, Alacritty follows the Rust compiler's style guidelines:
https://rust-lang.github.io/api-guidelines
All comments should be fully punctuated with a trailing period. This applies both to regular and documentation comments.
Alacritty's release process aims to provide stable and well tested releases without having to hold back new features during the testing period.
To achieve these goals, a new branch is created for every major release. Both the release candidates and the final version are only committed and tagged in this branch. The master branch only tracks development versions, allowing us to keep the branches completely separate without merging releases back into master.
The exact steps for an exemplary 0.2.0
release might look like this:
0.2.0-dev
v0.2
branch is created for the release0.2.0-rc1
v0.2.0-rc1
v0.2.0-rc1
tag0.3.0-dev
and the -dev
suffix is removed from the 0.2.0-dev
changelog0.2.0
v0.2.0
v0.2.0
tagOn master and with new planned releases, only the minor version is bumped. This makes it possible to create bug fix releases by incrementing the patch version of a previous minor release, without having to adjust the next planned release's version number.
The exact steps for an exemplary 0.2.3
release might look like this:
0.3.0-dev
and the latest release was 0.2.2
v0.2
branch is checked outv0.2
branchv0.2.3-rc1
and the changelog is updated to include all fixes0.2.3
releaseThe alacritty_terminal
crate is released in synchronization with alacritty
, keeping the -dev
and -rcX
version suffix identical across the two crates. As soon as the new Alacritty stable release is made, releases are tagged as alacritty_terminal_vX.Y.Z
and pushed to crates.io. During a release, only the patch version is bumped on master, since there haven't been any changes since the last release yet.
If there are any outstanding questions about contributing to Alacritty, they can be asked on the Alacritty issue tracker.
As a more immediate and direct form of communication, the Alacritty IRC channel (#alacritty
on Libera.Chat) can be used to contact many of the Alacritty contributors.