You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Please make sure to document all user-facing changes in the `CANGELOG.md` file.
1
+
Please make sure to document all user-facing changes in the `CHANGELOG.md` file.
2
2
3
3
Draft PRs are always welcome, though unless otherwise requested PRs will not be reviewed until all required and optional CI steps are successful and they have left the draft stage.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+79-16Lines changed: 79 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,56 +11,119 @@ Table of Contents:
11
11
2.[Performance](#performance)
12
12
3.[Documentation](#documentation)
13
13
4.[Style](#style)
14
-
4.[Contact](#contact)
14
+
4.[Release Process](#release-process)
15
+
5.[Contact](#contact)
15
16
16
17
## Feature Requests
17
18
18
-
Feature requests should be reported in the [Alacritty issue tracker](https://github.com/jwilm/alacritty/issues). To reduce the number of duplicates, please make sure to check the existing [enhancement](https://github.com/jwilm/alacritty/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Aenhancement) and [missing feature](https://github.com/jwilm/alacritty/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3A%22B+-+missing+feature%22) issues.
19
+
Feature requests should be reported in the
20
+
[Alacritty issue tracker](https://github.com/jwilm/alacritty/issues). To reduce the number of
21
+
duplicates, please make sure to check the existing
If a bug was not present in a previous version of Alacritty, providing the exact commit which introduced the regression helps out a lot.
32
+
If a bug was not present in a previous version of Alacritty, providing the exact commit which
33
+
introduced the regression helps out a lot.
25
34
26
35
## Patches / Pull Requests
27
36
28
37
All patches have to be sent on Github as [pull requests](https://github.com/jwilm/alacritty/pulls).
29
38
30
-
If you are looking for a place to start contributing to Alacritty, take a look at the [help wanted](https://github.com/jwilm/alacritty/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) and [easy](https://github.com/jwilm/alacritty/issues?q=is%3Aopen+is%3Aissue+label%3A%22D+-+easy%22) issues.
39
+
If you are looking for a place to start contributing to Alacritty, take a look at the
Please note that the minimum supported version of Alacritty is Rust 1.36.0. All patches are expected to work with the minimum supported version.
45
+
Please note that the minimum supported version of Alacritty is Rust 1.36.0. All patches are expected
46
+
to work with the minimum supported version.
33
47
34
48
### Testing
35
49
36
-
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:
50
+
To make sure no regressions were introduced, all tests should be run before sending a pull request.
51
+
The following command can be run to test Alacritty:
37
52
38
53
```
39
54
cargo test
40
55
```
41
56
42
-
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.
57
+
Additionally if there's any functionality included which would lend itself to additional testing,
58
+
new tests should be added. These can either be in the form of Rust tests using the `#[test]`
59
+
annotation, or Alacritty's ref tests.
43
60
44
-
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.
61
+
To record a new ref test, a release version of the patched binary should be created and run with the
62
+
`--ref-test` flag. After closing the Alacritty window, or killing it (`exit` and `^D` do not work),
63
+
some new files should have been generated in the working directory. Those can then be copied to the
64
+
`./tests/ref/NEW_TEST_NAME` directory and the test can be enabled by editing the `ref_tests!` macro
65
+
in the `./tests/ref.rs` file. When fixing a bug, it should be checked that the ref test does not
66
+
complete correctly with the unpatched version, to make sure the test case is covered properly.
45
67
46
68
### Performance
47
69
48
-
Alacritty mainly uses the [vtebench](https://github.com/jwilm/vtebench) tool for testing Alacritty's performance. Any change which could have an impact on Alacritty's performance, should be tested with it to prevent potential regressions.
70
+
Alacritty mainly uses the [vtebench](https://github.com/jwilm/vtebench) tool for testing Alacritty's
71
+
performance. Any change which could have an impact on Alacritty's performance, should be tested with
72
+
it to prevent potential regressions.
49
73
50
74
### Documentation
51
75
52
-
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.
76
+
Code should be documented where appropriate. The existing code can be used as a guidance here and
77
+
the general `rustfmt` rules can be followed for formatting.
53
78
54
-
If any change has been made to the `config.rs` file, these changes should also be documented in the example configuration file `alacritty.yml`.
79
+
If any change has been made to the `config.rs` file, these changes should also be documented in the
80
+
example configuration file `alacritty.yml`.
55
81
56
-
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`. 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](https://keepachangelog.com).
82
+
Changes compared to the latest Alacritty release which have a direct effect on the user (opposed to
83
+
things like code refactorings or documentation/tests) additionally need to be documented in the
84
+
`CHANGELOG.md`. The existing entries should be used as a style guideline. The change log should be
85
+
used to document changes from a user-perspective, instead of explaining the technical background
86
+
(like commit messages). More information about Alacritty's change log format can be found
87
+
[here](https://keepachangelog.com).
57
88
58
89
### Style
59
90
60
-
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`.
91
+
All Alacritty changes are automatically verified by CI to conform to its rustfmt guidelines. If a CI
92
+
build is failing because of formatting issues, you can install rustfmt using `rustup component add
93
+
rustfmt` and then format all code using `cargo fmt`.
94
+
95
+
# Release Process
96
+
97
+
Alacritty's release process aims to provide stable and well tested releases without having to hold
98
+
back new features during the testing period.
99
+
100
+
To achieve these goals, a new branch is created for every new release. Both the release candidates
101
+
and the final version are only comitted and tagged in this branch. The master branch only tracks
102
+
development versions, allowing us to keep the branches completely separate without merging releases
103
+
back into master.
104
+
105
+
The exact steps for an exemplary `1.2.3` release might look like this:
106
+
1. Initially, the version on the latest master is `1.2.3-dev`
107
+
2. A new `v1.2.3` branch is created for the release
108
+
3. On master, the version is bumped to `1.2.4-dev`
109
+
and the `-dev` is stripped from previous change log entries
110
+
4. In the branch, the version is bumped to `1.2.3-rc1`
111
+
5. The new commit in the branch is tagged as `v1.2.3-rc1`
112
+
6. A GitHub release is created for the `v1.2.3-rc1` tag
113
+
7. The changelog since the last release (stable or RC)
114
+
is added to the GitHub release description
115
+
8. Bug fixes are cherry-picked from master into the branch and steps 4-7
116
+
are repeated until no major issues are found in the release candidates
117
+
9. In the branch, the version is bumped to `1.2.3`
118
+
10. The new commit in the branch is tagged as `v1.2.3`
119
+
11. A GitHub release is created for the `v1.2.3` tag
120
+
12. The changelog since the last stable release (**not** RC)
121
+
is added to the GitHub release description
61
122
62
123
# Contact
63
124
64
-
If there are any outstanding questions about contributing to Alacritty, they can be asked on the [Alacritty issue tracker](https://github.com/jwilm/alacritty/issues).
125
+
If there are any outstanding questions about contributing to Alacritty, they can be asked on the
As a more immediate and direct form of communication, the Alacritty IRC channel (`#alacritty` on Freenode) can be used to contact many of the Alacritty contributors.
128
+
As a more immediate and direct form of communication, the Alacritty IRC channel (`#alacritty` on
129
+
Freenode) can be used to contact many of the Alacritty contributors.
0 commit comments