Skip to content

Commit e46dc59

Browse files
Add a note on how Bevy uses milestones to the Contributing Guide (#2197)
1 parent 07248eb commit e46dc59

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

content/learn/contribute/reference/triage.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,42 @@ There are several paths for PRs to be closed:
121121

122122
When closing a PR, check if it has an issue linked. If it does not, you should strongly consider creating an issue and linking the now-closed PR to help make sure the previous work can be discovered and credited.
123123

124+
## Milestones, Roadmaps and Work Planning
125+
126+
Bevy is, to a large degree, a project powered by volunteers, each with their own motivations and goals.
127+
The usual estimation and long-term planning difficulties of software are amplified dramatically: this is why Bevy does not maintain a central roadmap.
128+
129+
Despite this, some degree of work planning is important, as both a coordination and quality control mechanism.
130+
This is generally fairly decentralized and organic, relying on temporary, focused working groups and milestones.
131+
132+
Each release (both major and minor) has an [associated milestone](https://github.com/bevyengine/bevy/milestones).
133+
For example, the 0.5 milestone would be for the major Bevy version 0.5 release,
134+
while the 0.5.1 milestone would be for a minor patch release for Bevy 0.5.
135+
136+
Minor version milestones are intended for work and issues that are either particularly critical to backport fixes for,
137+
or extremely low risk non-breaking improvements (such as documentation improvements or simple methods).
138+
When enough changes have accumulated, maintainers will create a new branch for the minor version,
139+
cherrypicking merged PRs in that milestone onto that branch and then publishing it.
140+
Breaking changes cannot be shipped in a minor version (due to semantic versioning),
141+
and complex changes are both hard to cherrypick and challenging to use.
142+
143+
By contrast, major version milestones serve three purposes:
144+
145+
1. Tracking high-value, ready-to-implement or reviewable work that would be useful for contributors to tackle this cycle.
146+
2. Coordinating complex efforts that would be good to ship in a single cycle to avoid shipping half-complete features or refactors.
147+
3. Ensuring that we do not ship major bugs, shoddy documentation or inconsistent APIs.
148+
149+
At the start of each release cycle, the milestone will tend towards the first two use cases.
150+
As we near the end, the milestone is gradually trimmed down to only the most critical problems that would justify delaying a release.
151+
It's common to move issues and PRs that are near completion or still helpful to implement
152+
into the milestone for the major release after the current milestone.
153+
154+
Members of the triage team should follow these guidelines for how we use milestones,
155+
but are encouraged to add, remove and modify milestones for various work, based on their own subjective judgement
156+
of the importance of the work, how well it aligns with our current collective goals, and its current state.
157+
When you assign work to a milestone (or take it out of it), try to leave a short comment justifying why you have done so,
158+
so others can understand (and perhaps argue with) your rationale.
159+
124160
## Triage Team
125161

126162
Members of the Triage Team within the Bevy organization have permissions to label and close issues, though they do not have merge rights or special authority. Anyone is free to join as long as:

0 commit comments

Comments
 (0)