From 0a2e1834764098ae8899e8426d9f3fc7bfa03d8b Mon Sep 17 00:00:00 2001 From: Miles Silberling-Cook Date: Thu, 27 Mar 2025 13:46:39 -0400 Subject: [PATCH] Add basic release content tagging workflow (#18568) # Objective This PR begins integrating the new releate-content drafting process (https://github.com/bevyengine/bevy/pull/18427) into our GitHub workflows. It's similar to what we had before: Messages are posted to PRs tagged with `M-Needs-Release-Note` or `M-Needs-Migration-Guide` asking them to add the required material and linking to the instructions. These messages do not trigger if the PR already has modified files in the `release-notes` or `migration-guides` directories (respectively). I have also re-arranged and content slightly (to remove the need for a directory with the current version number), tweaked the language, and switched the templates to use the [standard markdown frontmatter format](https://jekyllrb.com/docs/front-matter/). ## Reviewer Questions + Do we want to add a CI rule actually requiring tagged PRs to create/modify files in the correct directories, or is the message prompt enough? + Do we want to add a CI rule to lint the metadata, for example to enforce that the PR number is included in the files it modifies? --- .github/workflows/action-on-PR-labeled.yml | 54 +++++++++++++++++-- release-content/README.md | 3 ++ release-content/migration-guides/.gitkeep | 0 .../migration_guides.md | 9 ++-- release-content/migration_guides_template.md | 30 +++++++++++ release-content/release-notes/.gitkeep | 0 .../release_notes.md | 8 +-- release-content/release_notes_template.md | 19 +++++++ working-migration-guides/template.md | 9 ---- working-release-notes/template.md | 11 ---- 10 files changed, 110 insertions(+), 33 deletions(-) create mode 100644 release-content/README.md create mode 100644 release-content/migration-guides/.gitkeep rename working-migration-guides/README.md => release-content/migration_guides.md (83%) create mode 100644 release-content/migration_guides_template.md create mode 100644 release-content/release-notes/.gitkeep rename working-release-notes/README.md => release-content/release_notes.md (87%) create mode 100644 release-content/release_notes_template.md delete mode 100644 working-migration-guides/template.md delete mode 100644 working-release-notes/template.md diff --git a/.github/workflows/action-on-PR-labeled.yml b/.github/workflows/action-on-PR-labeled.yml index 9887494a48..9e5835c1f7 100644 --- a/.github/workflows/action-on-PR-labeled.yml +++ b/.github/workflows/action-on-PR-labeled.yml @@ -12,19 +12,63 @@ permissions: pull-requests: 'write' jobs: - comment-on-breaking-change-label: + comment-on-migration-guide-label: runs-on: ubuntu-latest - if: github.event.label.name == 'M-Needs-Migration-Guide' && !contains(github.event.pull_request.body, '## Migration Guide') + if: github.event.label.name == 'M-Needs-Migration-Guide' steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 2 + - name: Get changes + id: get_changes + shell: bash {0} + run: | + git fetch --depth=1 origin $BASE_SHA + git diff --exit-code $BASE_SHA $HEAD_SHA -- ./release-content/migration-guides + echo "found_changes=$?" >> $GITHUB_OUTPUT + env: + BASE_SHA: ${{ github.event.pull_request.base.sha }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} - uses: actions/github-script@v7 + if: steps.get_changes.outputs.found_changes == '0' with: script: | await github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, - body: `It looks like your PR is a breaking change, but you didn't provide a migration guide. + body: `It looks like your PR is a breaking change, but **you didn't provide a migration guide**. - Could you add some context on what users should update when this change get released in a new version of Bevy? - It will be used to help writing the migration guide for the version. Putting it after a \`## Migration Guide\` will help it get automatically picked up by our tooling.` + Please review the [instructions for writing migration guides](https://github.com/bevyengine/bevy/tree/main/release-content/migration_guides.md), then expand or revise the content in the [migration guides directory](https://github.com/bevyengine/bevy/tree/main/release-content/migration-guides) to reflect your changes.` + }) + comment-on-release-note-label: + runs-on: ubuntu-latest + if: github.event.label.name == 'M-Needs-Release-Note' + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 2 + - name: Get changes + id: get_changes + shell: bash {0} + run: | + git fetch --depth=1 origin $BASE_SHA + git diff --exit-code $BASE_SHA $HEAD_SHA -- ./release-content/release-notes + echo "found_changes=$?" >> $GITHUB_OUTPUT + env: + BASE_SHA: ${{ github.event.pull_request.base.sha }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + - uses: actions/github-script@v7 + if: steps.get_changes.outputs.found_changes == '0' + with: + script: | + await github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: `It looks like your PR has been selected for a highlight in the next release blog post, but **you didn't provide a release note**. + + Please review the [instructions for writing release notes](https://github.com/bevyengine/bevy/tree/main/release-content/release_notes.md), then expand or revise the content in the [release notes directory](https://github.com/bevyengine/bevy/tree/main/release-content/release_notes) to showcase your changes.` }) diff --git a/release-content/README.md b/release-content/README.md new file mode 100644 index 0000000000..56fd2b8a06 --- /dev/null +++ b/release-content/README.md @@ -0,0 +1,3 @@ +# Release Content + +This directory contains drafts of documentation for the current development cycle, which will be published to the website during the next release. You can find more information in the [release notes](./release_notes.md) and [migration guide](./migration_guide.md) files. diff --git a/release-content/migration-guides/.gitkeep b/release-content/migration-guides/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/working-migration-guides/README.md b/release-content/migration_guides.md similarity index 83% rename from working-migration-guides/README.md rename to release-content/migration_guides.md index 291ff8eb54..b1fe48b31e 100644 --- a/working-migration-guides/README.md +++ b/release-content/migration_guides.md @@ -11,14 +11,15 @@ Bevy asks authors (and reviewers) to write a draft migration guide as part of th ## Where to put your migration guides Each major Bevy version (e.g. 0.12, or 2.0) will get its own migration guide. -The draft migration guides are organized into a folder of the same name inside of `bevyengine/bevy/working-migration-guides`. +The draft migration guides for the current cycle are organized in the `bevyengine/bevy/release-content/migration-guides` folder. -When we publish our first release candidate for a cycle, these notes are moved from `bevyengine/bevy`, and into `bevyengine/bevy-website`, +When we publish our first release candidate for a cycle, these notes are merged together and moved from `bevyengine/bevy` into `bevyengine/bevy-website`, where they will receive a final editing pass. -## What to put in your draft migration guide +If your PR introduces a new breaking change relative to the previous version, you should start a new guide by copying [the template](./migration_guides_template.md) into a new file in the `migration-guides` folder. +You should also update the existing migration guides in the other files, if your change effects them. -A `template.md` file is provided in `bevyengine/bevy/working-migration-guides`: copy-paste that to get started! +## What to put in your draft migration guide Migration guides are intended to briefly communicate: diff --git a/release-content/migration_guides_template.md b/release-content/migration_guides_template.md new file mode 100644 index 0000000000..5e02375c89 --- /dev/null +++ b/release-content/migration_guides_template.md @@ -0,0 +1,30 @@ +--- +title: Feature that broke +pull_requests: [14791, 15458, 15269] +--- + +Copy the contents of this file into a new file in `./migration-guides`, update the metadata, and add migration guide content here. + +## Goals + +Aim to communicate: + +- What has changed since the last release? +- Why did we make this breaking change? +- How can users migrate their existing code? + +## Style Guide + +Keep it short and sweet: + +- Use bullet points and make sure it's searchable. +- Avoid headings. If you must, use only level-two headings. +- Use backticks for types (e.g. `Vec`) in either the title or the body. +- Diff codeblocks can also be useful for succinctly communicating changes. + +```diff +fn my_system(world: &mut World) { ++ world.new_method(); +- world.old_method(); +} +``` diff --git a/release-content/release-notes/.gitkeep b/release-content/release-notes/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/working-release-notes/README.md b/release-content/release_notes.md similarity index 87% rename from working-release-notes/README.md rename to release-content/release_notes.md index e7577c08ef..319c66e5c9 100644 --- a/working-release-notes/README.md +++ b/release-content/release_notes.md @@ -11,14 +11,14 @@ Bevy asks authors (and reviewers) to write draft release notes as part of the pu ## Where to put your release notes Each major Bevy version (e.g. 0.12, or 2.0) will get its own set of release notes. -The draft release notes are organized into a folder of the same name inside of `bevyengine/bevy/working-release-notes`. +The draft release notes are organized in the `bevyengine/bevy/release-content/release-notes` folder. -When we publish our first release candidate for a cycle, these notes are moved from `bevyengine/bevy`, and into `bevyengine/bevy-website`, +When we publish our first release candidate for a cycle, these notes are merged together and moved from `bevyengine/bevy` into `bevyengine/bevy-website`, where they will receive a final editing pass and any multimedia. -## What to put in your draft release notes +To start a new release note, copy-paste [the template](./release_notes_template.md) into a new file in the `release-notes` folder. -A `template.md` file is provided in `bevyengine/bevy/working-release-notes`: copy-paste that to get started! +## What to put in your draft release notes Release notes are intended to capture the essence of: diff --git a/release-content/release_notes_template.md b/release-content/release_notes_template.md new file mode 100644 index 0000000000..0a4110a5cb --- /dev/null +++ b/release-content/release_notes_template.md @@ -0,0 +1,19 @@ +--- +title: Feature name +authors: ["@FerrisTheCrab", "@BirdObsessed"] +pull_requests: [14791, 15458, 15269] +--- + +Copy the contents of this file into `./release-notes`, update the metadata, and add release note content here. + +## Goals + +Answer the following: + +- What has been changed or added? +- Why is this a big deal for users? +- How can they use it? + +## Style Guide + +You may use markdown headings levels two and three, and must not start with a heading. Prose is appreciated, but bullet points are acceptable. Copying the introduction from your PR is often a good place to start. diff --git a/working-migration-guides/template.md b/working-migration-guides/template.md deleted file mode 100644 index 9287edca03..0000000000 --- a/working-migration-guides/template.md +++ /dev/null @@ -1,9 +0,0 @@ -# Feature that broke (remember to update the file name) - -prs = [14791, 15458, 15269] - -Add migration guide content here. Use bullet points, make sure it's searchable. Briefly communicate: - -- what has changed since the last release? -- why did we make this breaking change? -- how can users migrate their existing code? diff --git a/working-release-notes/template.md b/working-release-notes/template.md deleted file mode 100644 index e031a418c9..0000000000 --- a/working-release-notes/template.md +++ /dev/null @@ -1,11 +0,0 @@ -# Feature Name (remember to update the file name to match) - -authors = ["@FerrisTheCrab", "@BirdObsessed"] -contributors = ["@HelpfulHelper"] -prs = [14791, 15458, 15269] - -Add release note content here. Answer: - -- what has been changed or added? -- why is this a big deal for users? -- how can they use it?