New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Release.md #5622
base: trunk
Are you sure you want to change the base?
Add Release.md #5622
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Noticed a few typos while reading. Hope this is helpful!
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thought: I see no direction regarding the title, but maybe we don't need it?
Provides an overview of our release process, so releases aren't single-bus factor anymore.