Add Release.md #5622
Add Release.md #5622
Conversation
Co-authored-by: Imbris <2002109+Imberflur@users.noreply.github.com>
|
@Imberflur thanks! |
|
I'll take on review for this. Warning: I'll have a lot of (non-blocking) feedback (😅), but I think this is a big net improvement over nothing. |
There was a problem hiding this comment.
I think this is an overall massive improvement over having nothing written.
I've hit my timebox for feedback for this round, and I suspect I'll have more once I dedicate more time to this. However, I'm happy to implement even this feedback I have as an additional PR. I think all the important details are already in this new document, and waiting to land it for perfection sounds counterproductive.
I've noted things that I feel strongly about with checkboxes.
I used Conventional Comments in this review! I hope they help with clarity and tone. 🙂
|
|
||
| Anyone can perform most of these steps, except actually publishing the crates. | ||
|
|
||
| Currently only @kvark and @cwfitzgerald can publish all crates. @grovesNL can also publish `wgpu` crates. @jimblandy can publish `naga` crates. @msiglreith can publish `d3d12`. |
There was a problem hiding this comment.
question(non-blocking): The "bus factor" seems low; we don't seem to have room for contingency for cutting releases (i.e., in the scenario you (@cwfitzgerald) suddenly disappear from the project). Is there a current plan to increase access to this?
I can reasonably see folks disagreeing with this perception, so I'll prompt @gfx-rs/wgpu and @gfx-rs/naga here, too.
There was a problem hiding this comment.
I always wondered about this bit a lil. I kinda assumed that @jimblandy can also push releases so my mind was at ease but now I'm alarmed. Seems risky!
(too many goes into the other direction of too risky ofc, don't think all of the maintainers should have the publish keys, that's just asking for trouble)
There was a problem hiding this comment.
Added to the 2024-05-08 agenda.
|
|
||
| ## Structure | ||
|
|
||
| We do a major breaking release every 12 weeks. This happens no matter the status of various in-flight projects. |
There was a problem hiding this comment.
thought: …unless we have a reason to postpone, like last time? 😈
I think there are some conditions under which a release is postponed, but noting that they are only under emergent conditions sounds…maybe redundant? 🤷🏻♂️
|
|
||
| ## Major Release Process | ||
|
|
||
| Approx 1 Week Before: |
There was a problem hiding this comment.
question: These seem like poor man's section headers. Why not formally make a section instead, i.e.:
| Approx 1 Week Before: | |
| ### Approx. 1 Week Before | |
…?
This feedback also applies to other headers like it.
| ## Major Release Process | ||
|
|
||
| Approx 1 Week Before: | ||
| - Determine if `glow` (@groves), `metal-rs` (@kvark and @cwfitzgerald) or any other dependant crates will need a release. If so, coordinate with their maintainers. |
There was a problem hiding this comment.
question: Is there more specific direction we can give here? The only criteria I can think of is "make sure we're depending on published crates on Crates.io, rather than, say, git dependencies".
| ## Major Release Process | ||
|
|
||
| Approx 1 Week Before: | ||
| - Determine if `glow` (@groves), `metal-rs` (@kvark and @cwfitzgerald) or any other dependant crates will need a release. If so, coordinate with their maintainers. |
There was a problem hiding this comment.
nitpick/typo: s/dependant/dependent in US English, though this is valid for British English.
suggestion: Note that we're talking about out-of-tree dependencies.
Combined feedback:
| - Determine if `glow` (@groves), `metal-rs` (@kvark and @cwfitzgerald) or any other dependant crates will need a release. If so, coordinate with their maintainers. | |
| - Determine if `glow` (@groves), `metal-rs` (@kvark and @cwfitzgerald) or any other dependent crates outside of the repo will need a release. If so, coordinate with their maintainers. |
|
|
||
| ## Patch Release Process | ||
| - Enumerate all PRs that haven't been backported yet. These use the `needs-backport` label. [GH Link](https://github.com/gfx-rs/wgpu/issues?q=label%3A%22PR%3A+needs+back-porting) | ||
| - On _your own branch_ based on the latest release branch. Cherry-pick the PRs that need to be backported. When modifying the commits, use --append to retain their original authorship. |
There was a problem hiding this comment.
typo: A comma should separate these otherwise incomplete sentences, not a period.
style: Backticks around CLI args., please!
issue: It's unclear what CLI you're actually talking about. --append doesn't exist in the git-cherry-pick or git-commit CLIs. I suspect you meant the git commit --amend flag? 🤔
Combined feedback:
| - On _your own branch_ based on the latest release branch. Cherry-pick the PRs that need to be backported. When modifying the commits, use --append to retain their original authorship. | |
| - On _your own branch_ based on the latest release branch, cherry-pick the PRs that need to be backported. When modifying the commits, use `--amend` to retain their original authorship. |
There was a problem hiding this comment.
Yes, I use a git gui so I click the button that starts with an a :)
| - On _your own branch_ based on the latest release branch. Cherry-pick the PRs that need to be backported. When modifying the commits, use --append to retain their original authorship. | ||
| - Remove the `needs-backport` label from the PRs. | ||
| - Fix the changelogs items and add a new header for the patch release with the release version and date. | ||
| - Once all the PRs are cherry-picked, look at the diff between HEAD and the previous patch release. See what crates changed. |
There was a problem hiding this comment.
style: Backticks for refs., please!
suggestion: An example CLI invocation might be nice here.
| - Once all the PRs are cherry-picked, look at the diff between HEAD and the previous patch release. See what crates changed. | |
| - Once all the PRs are cherry-picked, look at the diff between `HEAD` and the previous patch release (i.e., via `git diff v0.20.0..HEAD`). See what crates changed. |
| @@ -0,0 +1,79 @@ | |||
| This is an overview of how to run wgpu releases. | |||
There was a problem hiding this comment.
style: backticks plz
suggestion: I'd like to distinguish wgpu-the-crate from wgpu-the-Git-repository.
| This is an overview of how to run wgpu releases. | |
| This is an overview of how to run releases in the `wgpu` repository. |
|
|
||
| We do a major breaking release every 12 weeks. This happens no matter the status of various in-flight projects. | ||
|
|
||
| We do a patch releases as needed in the weeks between major releases. Once a new major release is cut, we stop doing patch releases for the previous major release unless there is a critical bug or a compilation issue. |
There was a problem hiding this comment.
thought: This seems particularly important for users to understand. Not sure if there's anything actionable here, but this was a nice bit of clarity to have.
| - Create a new release on the `wgpu` repo with the changelog and a tag called `vX.Y.Z`. | ||
| - Create a branch with the with the new version `vX.Y` and push it to the repo. | ||
| - Publish the link to the github release in the following places. | ||
| - [r/rust](https://www.reddit.com/r/rust/). |
There was a problem hiding this comment.
thought: I see no direction regarding the title, but maybe we don't need it?
ErichDonGubler
added
the
area: infrastructure
Provides an overview of our release process, so releases aren't single-bus factor anymore.