Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Add Release.md #5622

Merged
merged 2 commits into from
Jun 12, 2024
Merged

Add Release.md #5622

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4018043
Add Release.md
cwfitzgerald Apr 29, 2024
a62b2ca
Apply suggestions from code review
cwfitzgerald May 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
79 changes: 79 additions & 0 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
This is an overview of how to run wgpu releases.
Copy link
Member

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.

Suggested change
This is an overview of how to run wgpu releases.
This is an overview of how to run releases in the `wgpu` repository.


## Structure

We do a major breaking release every 12 weeks. This happens no matter the status of various in-flight projects.
ErichDonGubler marked this conversation as resolved.
Show resolved Hide resolved

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.
ErichDonGubler marked this conversation as resolved.
Show resolved Hide resolved

## People

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`.
ErichDonGubler marked this conversation as resolved.
Show resolved Hide resolved
Comment on lines +11 to +13
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: It seems odd to separate these into two paragraphs.

nitpick: Comma after Currently.

Combined feedback:

Suggested change
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`.
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`.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thought: This might be better constructed as a list or table, instead?


## Major Release Process

Approx 1 Week Before:
Copy link
Member

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.:

Suggested change
Approx 1 Week Before:
### Approx. 1 Week Before

…?

This feedback also applies to other headers like it.

- Determine if `glow` (@groves), `metal-rs` (@kvark and @cwfitzgerald) or any other dependant crates will need a release. If so, coordinate with their maintainers.
Copy link
Member

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".

Copy link
Member

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:

Suggested change
- 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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion(non-blocking): I think it'd be nicer to have the directive be simpler with more supporting information/points of contact for individual repos as a sub-list:

Suggested change
- 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 dependent crates will need a release. If so, coordinate with their maintainers. Known points of contact:
- `glow` (@groves)
- `metal-rs` (@kvark and @cwfitzgerald)

- Go through the changelog:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: "the changelog" is less concrete than "the CHANGELOG.md file" (though less verbose. I think including the actual file location in this guide is important, so I think we should do 1 of 2 things:

  1. Define what "the changelog" means somewhere earlier.
  2. Replace all instances of "the changelog" with "the CHANGELOG.md file".

I'd vote for (1), but (2) also seems reasonable.

- Re-categorize miscategorized items.
- Edit major changes so a user can easily understand what they need to do.
- Add missing major changes that users need to know about.
- Copy-edit the changelog for clarity.

Day of Release:
- Update all crates to be the new version. We bump all versions even if there were no changes.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: I strongly recommend that this and other lists be ordered, since this is fundamentally an ordered sequence of steps to execute. Just having numbers can help a reader mentally keep track of what they're doing while reading, which is important for something load-bearing like this process.

- `d3d12`
- `naga`
- `naga-cli`
- `wgpu-types`
- `wgpu-hal`
- `wgpu-core`
- `Cargo.toml` (this covers the rest of the crates).
- Ensure `glow` and `metal` are updated to the latest version if needed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question(non-blocking): I feel like it's risky to have dependency changes the day of a release; most people consuming mainline will have been testing with the previous versions, and won't have a chance to catch issues. Could we at least move this to be approximately a week before?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is supposed to be "move from git to crates with no/minimal code changes, as you just got them to publish a release".

- Add a new header for the changelog with the release version and date.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Add a concrete example from the CHANGELOG.

Suggested change
- Add a new header for the changelog with the release version and date.
- Add a new `## Header` for the changelog with the release version and date (i.e., `## v0.20.0 (2024-04-28)`).

- Create a PR with all of the version changes and changelog updates.
- Once the PR is CI clean, (force) merge it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: What does (force) mean in this case?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I understand now. Suggested edit:

Suggested change
- Once the PR is CI clean, (force) merge it.
- Once the PR is CI clean, forcefully `Enable auto-merge (rebase)` it without waiting for approval using the `Merge without waiting for requirements to be met (bypass branch protections)` checkbox.

- Checkout `trunk` with the merged PR.
- Publish! These commands can be pasted directly into your terminal in a single command, and they will publish everything.
```bash
cargo publish -p d3d12
cargo publish -p naga
cargo publish -p naga-cli
cargo publish -p wgpu-types
cargo publish -p wgpu-hal --all-features
cargo publish -p wgpu-core --all-features
Comment on lines +45 to +46
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: Why is --all-features here? I'm pretty sure we can remove it. I don't think it actually changes the publish process, but is accepted across all cargo invocations Just Because™.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because core and hal need some backends enabled, otherwise it will be unhappy. --all-features is the easiest way to get there.

cargo publish -p wgpu
cargo publish -p wgpu-info
```
Comment on lines +39 to +49
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • issue: I can see this crate list becoming out-of-date. I'd strongly prefer this not be the case, and that we use instead members of the main crate workspace whose Cargo.toml does not contain package.publish = false as our source of truth.

question(non-blocking): Have we considered consolidating these (and a few other) steps with a tool like cargo-release?

I actually have greatly enjoyed cargo-release in my own FOSS efforts, and I think it can automate a few steps of the process as it's written (and also tackle the issue I mention above). @gfx-rs/wgpu, @gfx-rs/naga: Shall we discuss this in our next wgpu maintainers meeting?

Copy link
Member

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.

- Create a new release on the `wgpu` repo with the changelog and a tag called `vX.Y.Z`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Continue with a concrete example here.

Combined feedback:

Suggested change
- Create a new release on the `wgpu` repo with the changelog and a tag called `vX.Y.Z`.
- Create a new release on the `wgpu` repo with the changelog and a tag called `vX.Y.Z` (i.e., `v0.20.0`).

- Create a branch with the with the new version `vX.Y` and push it to the repo.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: s/with the with the/with the/ (though I'd prefer "called", to be consistent with the previous step).

suggestion: Continue with a concrete example here.

Combined feedback:

Suggested change
- Create a branch with the with the new version `vX.Y` and push it to the repo.
- Create a branch called `vX.Y` (i.e., `v0.20`) and push it to the repo.

- Publish the link to the github release in the following places.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: Proper capitalization of GitHub, as with other places in this doc.

typo: A colon is preferred for serializing lists to English.

suggestion: Continue with a concrete example.

Combined feedback:

Suggested change
- Publish the link to the github release in the following places.
- Publish the link to the GitHub release (i.e., <https://github.com/gfx-rs/wgpu/releases/tag/v0.20.0>) in the following places:

- [r/rust](https://www.reddit.com/r/rust/).
Copy link
Member

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?

- Add an AMA comment.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Help folks who don't know what an AMA is to understand the term.

suggestion: Rust communities tend to value having sufficient context about the post's subject in comments, so new readers aren't lost. I think we'll mesh better with those communities if we also include something like the repo's description in the proposed AMA comment:

Combined feedback:

Suggested change
- Add an AMA comment.
- Add a comment to the post including:
- Some context about what WGPU is. It is recommended to use the repo's current description.
- An [Ask Me Anything](https://support.reddithelp.com/hc/en-us/articles/15484156913940-What-is-an-AMA-and-why-would-I-host-one) prompt.
- Anything else from the release that you may want to highlight.

Once accepted, it also seems helpful to update the next Add an AMA comment. to instead be Add a comment like in the steps for the previous post.

- Crosspost to [r/rust_gamedev](https://www.reddit.com/r/rust_gamedev/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Explain what crossposting is.

suggestion: Use a demonstrative for hopefully clearer language.

Suggested change
- Crosspost to [r/rust_gamedev](https://www.reddit.com/r/rust_gamedev/).
- [Crosspost](https://support.reddithelp.com/hc/en-us/articles/4835584113684-What-is-Crossposting) the previous post to [r/rust_gamedev](https://www.reddit.com/r/rust_gamedev/).

- Add an AMA comment.
- Include the r/rust post shortlink in the following posts as well:
- [wgpu matrix](https://matrix.to/#/#wgpu:matrix.org)
- [Rust Gamedev Discord](https://discord.gg/yNtPTb2) in the #crates channel
- [Bevy Discord](https://discord.com/invite/bevy) in the #rendering-dev channel
- [Graphics Programming Discord](https://discord.gg/6mgNGk7) in the #webgpu channel
- [Rust Community Discord](https://discord.gg/rust-lang-community) in the #games-and-graphics channel
Comment on lines +57 to +62
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: Need to indent to create a proper sub-list.

typo: Capitalization for wgpu matrix could be better, esp. to match other entries.

Combined feedback:

Suggested change
- Include the r/rust post shortlink in the following posts as well:
- [wgpu matrix](https://matrix.to/#/#wgpu:matrix.org)
- [Rust Gamedev Discord](https://discord.gg/yNtPTb2) in the #crates channel
- [Bevy Discord](https://discord.com/invite/bevy) in the #rendering-dev channel
- [Graphics Programming Discord](https://discord.gg/6mgNGk7) in the #webgpu channel
- [Rust Community Discord](https://discord.gg/rust-lang-community) in the #games-and-graphics channel
- Include the r/rust post shortlink in the following posts as well:
- [WGPU Matrix](https://matrix.to/#/#wgpu:matrix.org)
- [Rust Gamedev Discord](https://discord.gg/yNtPTb2) in the #crates channel
- [Bevy Discord](https://discord.com/invite/bevy) in the #rendering-dev channel
- [Graphics Programming Discord](https://discord.gg/6mgNGk7) in the #webgpu channel
- [Rust Community Discord](https://discord.gg/rust-lang-community) in the #games-and-graphics channel

- Complete the release's milestone on GitHub.
- Create a new milestone for the next release, in 12 weeks time.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: s/weeks/weeks'/

typo: A comma actually doesn't seem appropriate here, unless…

…suggestion: s/in 12 weeks' time/with due date set to 12 weeks from release/.

suggestion: Continue with the concrete example of 0.20.0.

Suggested change
- Create a new milestone for the next release, in 12 weeks time.
- Create a new milestone for the next release, with due date set to 12 weeks from this release's date (i.e., 0.20.0 released on 2024-04-28, so the next milestone `0.21.0` would be due on 2024-07-17).


## Patch Release Process
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: Most MD formatters (and other MD documents in the ) place spaces between the header and content.

Suggested change
## Patch Release Process
## Patch Release Process

This feedback also applies to other headers in this document.

- 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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick(non-blocking): IDK, I think the "natural" way of linking works is nicer-looking:

Suggested change
- 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)
- Enumerate all PRs that haven't been backported yet. These use the [`needs-backport` label](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.
Copy link
Member

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:

Suggested change
- 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.

Copy link
Member Author

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 :)

- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: s/changelogs/changelog's/

typo: Comma between phrases, i.e., …items, and….

Suggestion: Continue with the concrete example (i.e., 0.20.1).

Suggested change
- Fix the changelogs items and add a new header for the patch release with the release version and date.
- Fix the changelog's items, and add a new header for the patch release with the release version and date (i.e., `## 0.20.1 (2024-05-03)`).

- Once all the PRs are cherry-picked, look at the diff between HEAD and the previous patch release. See what crates changed.
Copy link
Member

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.

Suggested change
- 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.

- Bump all the versions of the crates that changed.
- Create a PR with all of the version changes and changelog updates into the release branch.
- Once the PR is CI clean, (force) rebase merge it.
- Checkout the release branch with the merged PR.
- Publish all relevant crates (see list above).
- Create a new release on the `wgpu` repo with the changelog and a tag called `vX.Y.Z` on the release branch.
- Backport the changelog and version bumps to the `trunk` branch.
- Ensure that any items in the newly-released changelog don't appear in the "unreleased" section of the trunk changelog.