Skip to content

Commit 2847c4d

Browse files
committed
Add an RFC defining policy for issuing patch releases.
1 parent 7d6859b commit 2847c4d

File tree

1 file changed

+58
-0
lines changed

1 file changed

+58
-0
lines changed

text/0000-patch-releases.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
- Start Date: (fill me in with today's date, YYYY-MM-DD)
2+
- RFC PR: [amaranth-lang/rfcs#0000](https://github.com/amaranth-lang/rfcs/pull/0000)
3+
4+
# Patch releases
5+
6+
## Summary
7+
[summary]: #summary
8+
9+
Change Amaranth versioning from `major.minor` to `major.minor.patch` after version 0.4, and define the backport policy for patch releases.
10+
11+
## Motivation
12+
[motivation]: #motivation
13+
14+
Amaranth 0.3 was released on 2021-12-16; almost two years ago. Several important bugs have been fixed in `main` since, most notably depending on a version of `Jinja2` that is no longer installable. At the moment the policy is to issue only `major.minor` releases, which was OK in the early days but no longer fits the project.
15+
16+
We should change the policy that is used for the next Amaranth release and later ones.
17+
18+
## Explanation
19+
[guide-level-explanation]: #guide-level-explanation
20+
21+
Amaranth feature releases all have the version of `major.minor.0`. The policy for these releases is unchanged and is tied to our two-step process for making breaking changes.
22+
23+
In addition to these releases, Amaranth now has bug-fix releases with the `major.minor.patch` versions. These are intended to address the need of the community to have bugs fixed before a next feature release can be made, and the policy is designed to minimize developer time spent on them.
24+
25+
Bug-fix releases are made when all of the following conditions are satisfied:
26+
- There is an issue that is fixed in the `main` branch.
27+
- A member of the community requests this issue to be fixed in a point release.
28+
- It is possible to fix the issue such that there is a high degree of confidence that the change will not break existing code using Amaranth with a `~=major.minor` version constraint.
29+
- A community member steps up to backport the fix to the release branch.
30+
- This could be one of the Amaranth maintainers, or anyone else. Amaranth maintainers have no obligation to back-port any fix.
31+
32+
## Drawbacks
33+
[drawbacks]: #drawbacks
34+
35+
This creates additional work for maintainers.
36+
37+
## Rationale and alternatives
38+
[rationale-and-alternatives]: #rationale-and-alternatives
39+
40+
- It would be possible to backport all feasible fixes as a policy.
41+
- This would significantly increase maintainer workload.
42+
- It is possible to keep the current policy.
43+
- Because we do not control all of the upstream dependencies (including Python), this seems untenable.
44+
45+
## Prior art
46+
[prior-art]: #prior-art
47+
48+
Rust has an even stricter bug-fix release policy: the Rust project only issues patch releases in cases of security issues, widespread miscompilations, or unintentional breaking changes.
49+
50+
## Unresolved questions
51+
[unresolved-questions]: #unresolved-questions
52+
53+
Should Amaranth SoC adopt the same policy?
54+
55+
## Future possibilities
56+
[future-possibilities]: #future-possibilities
57+
58+
Eventually, Amaranth may gain release engineers who will maintain long-living release branches.

0 commit comments

Comments
 (0)