Skip to content

Commit b1d814c

Browse files
ef4ef4
authored
Merge pull request #20754 from emberjs/kg-update-release-md
Update RELEASE.md
2 parents aa585a6 + 614b3c5 commit b1d814c

File tree

1 file changed

+238
-145
lines changed

1 file changed

+238
-145
lines changed

‎RELEASE.md

Lines changed: 238 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,241 @@
11
# Ember.js Releases
22

3-
## Concepts
4-
5-
* 6-week release cycle
6-
* weekly beta
7-
* Channels
8-
* Release (stable)
9-
* Beta
10-
* Canary
11-
* SemVer
12-
* Patch
13-
* Minor (point)
14-
* Major
15-
16-
---
17-
18-
## Ember Notes on Point Releases (Not Release Notes)
19-
20-
1. Check out `beta` branch and `git pull`
21-
1. Make sure any main commits that are conceptually `[{BUGFIX,DOC} {beta,release}]` are cherry-picked.
22-
1. `git push origin beta`, and `let ciBranch = kick off a CI build`
23-
1. `PRIOR_VERSION=v2.5.0-beta.1 ./bin/changelog.js | uniq | pbcopy`
24-
1. Open `CHANGELOG.md`, paste in the results of the previous script, and clean it up for human-readability.
25-
1. e.g. [BUGFIX beta] -> [BUGFIX], [DEPRECATE beta] -> [DEPRECATE], ...
26-
1. Revert [BUGFIX ...] -> [BUGFIX] Revert ...
27-
1. rm [DOC] (usually)
28-
1. rm other trivial things
29-
1. Backport CHANGELOG to main
30-
1. `await ciBranch`
31-
1. if CI succeeds, process
32-
1. if CI fails and it's a fix that doesn't need to be on main (e.g. linting or merge conflicts accidentally checked in), fix and retry.
33-
1. otherwise, start over
34-
1. Update `package.json` and `VERSION` file to use new version number
35-
1. git add/commit -m "Release v2.5.0-beta.2."
36-
1. `git tag v2.5.0-beta.2-ember-source`
37-
1. `git push origin v2.5.0-beta.2`, and `let ciTag = kick off a CI build` (to produce the assets)
38-
1. `git push origin beta`
3+
See [Ember.js Releases](https://emberjs.com/releases/) for an overview of how Ember.js releases work.
4+
5+
Ember.js consists of many packages. A release of `Ember.js` is considered complete upon the release blog post on [the Ember blog](https://blog.emberjs.com/tag/release).
6+
7+
This document is intended for maintainers of Ember.js. It describes the process for creating releases.
8+
9+
## ember-source
10+
11+
`ember-source` follows the Ember.js [release train/cycle](https://blog.emberjs.com/new-ember-release-process/). There is a stable release roughly every 6 weeks (every 4 versions excluding `x.0`) and a major release after every `x.12` release. New deprecations targeting the next major are not permitted to land after the `x.10` release. All public API changes should have an RFC and all features should behind feature flags. Features should not be enabled by default until the RFC has had a successful the [Ready for Release](https://github.com/emberjs/rfcs#ready-for-release) Stage.
12+
13+
Features, bugfixes, deprecations and other PRs are merged primarily to the `main` branch.
14+
These changes should be tagged according to what they are and whether they should be cherry-picked back to a beta, stable, or LTS release, see [Commit Tagging](https://github.com/emberjs/ember.js/blob/main/CONTRIBUTING.md#commit-tagging) in the CONTRIBUTING.md. These tags can also be in PR titles (as they are easier to edit after-the-fact than commit messages).
15+
16+
Changes to `main` are released on every commit to `s3` as `canary`.
17+
Weekly, changes on `main` are released as `alpha` on `npm`.
18+
19+
At least weekly, a contributor looks for changes from `main` that are tagged (and appropriate to be backported) to `beta` and creates a new `beta` release if there are changes.
20+
21+
In a beta cycle, there can be as few as 1 beta release or theoretically as many as needed, depending on the changes that land.
22+
23+
After six weeks, the beta is "promoted" to release by a contributor creating a new stable release. When the stable release is published, the prior release may be promoted to LTS, if is a successful candidate.
24+
25+
Generally changes should land on main. If a change needs to be backported to LTS, for example, it should be backported to beta to "settle" for a bit before being backported to release an the LTS.
26+
Rarely, a change is needed on an older version but not needed on main or newer versions. In those cases, the PR should target the branch.
27+
28+
### Creating a point release
29+
30+
1. Look for any PRs targeting release that have not been merged. Consider if they are ready to be merged, and if so, ensure the changes are also on `main` and `beta` if they are needed in those versions. Generally changes should be cherry-picked back to `release` so that they are not accidentally orphaned on older versions and so that they can be tested on `beta` and `main` before a point release.
31+
1. In `ember.js` repo, on main branch, `git pull`
32+
1. `git checkout release`
33+
1. `git pull`
34+
1. Look for any unreleased changes on `release` -- take note so you know what to expect in the CHANGELOG generation.
35+
1. Cherry-pick (using `git cherry-pick -x`) anything tagged `release` that was merged to main since the last release. To do this, look at merged PRs to find commits. The commit history isn't a good way to find these because it sorts by date, and some commits can be on old PRs that were finally merged. You may have to fix any conflicts. If this is beyond you, you can ask the original contributor to make a pull request to `release`.
36+
1. `git push` to let CI run. You must push changes before running the CHANGELOG generation as it uses the GitHub API to find PRs.
37+
1. Generate Changelog:
38+
```bash
39+
HEAD=release PRIOR_VERSION=v5.10.1-ember-source ./bin/changelog.js | uniq | pbcopy
40+
```
41+
42+
1. Put the results in `CHANGELOG.md` under a heading for the new point release. Clean up the changelog, see [Producing the CHANGELOG](#producing-the-changelog) for the details.
43+
1. Commit with message:
44+
```
45+
Add v5.10.2 to CHANGELOG for `ember-source`
46+
```
47+
48+
1. Update `package.json` version to:
49+
```
50+
5.10.2
51+
```
52+
53+
1. Commit with message:
54+
```
55+
Release v5.10.2-ember-source
56+
```
57+
58+
1. Tag commit:
59+
```bash
60+
git tag v5.10.2-ember-source
61+
```
62+
63+
1. Push tag:
64+
```bash
65+
git push origin v5.10.2-ember-source
66+
```
67+
68+
1. Push changes `git push`
69+
1. Cherry-pick changelog commit to `main` branch and to the `beta` branch.
70+
1. Draft release on Github, see [Creating a Release on Github](#creating-a-release-on-github).
71+
1. Wait for CI on the tag and check published to npm with `npm info ember-source`.
72+
73+
#### LTS Point release
74+
75+
Follow the above steps but begin with the `lts-5-8` branch (or whatever the LTS branch you are targeting is).
76+
This branch may need to be created if it does not exist from the tag.
77+
After release, if it is the latest LTS, tag as LTS with `npm dist-tag add [email protected] lts`.
78+
79+
### Creating a (n-th) beta release
80+
81+
1. In `ember.js` repo, on main branch, `git pull`
3982
1. `git checkout beta`
40-
1. `rm -rf dist && mkdir dist && cp ../components-ember/* dist/`
41-
1. Go to [https://github.com/emberjs/ember.js/releases](https://github.com/emberjs/ember.js/releases)
42-
1. Click on the most recent tag (2.5.0-beta.2), and then click "Edit"
43-
1. Start with `### Changelog` and copy/paste the changelog into the box
44-
1. Make the title `Ember 2.5.0-beta.2` and check "This is a pre-release" for betas
45-
1. Update [builds page](https://github.com/ember-learn/builds/tree/master/app/fixtures/ember)
46-
1. Deploy
47-
48-
---
49-
50-
## Ember Notes on Release (Not Release Notes)
51-
52-
Starting point: [https://gist.github.com/rwjblue/fb945e55c70d698d4074](https://gist.github.com/rwjblue/fb945e55c70d698d4074)
53-
54-
## LTS Releases
55-
56-
1. In Ember bower repo, `git co -b lts-2-4` , `git push origin`
57-
1. In `bin/publish_to_s3.js` and `bin/bower_ember_build`, add relevant "lts-2-4" lines (see https://github.com/emberjs/ember.js/commit/618de4fa036ab33dc760343decd355ede7b822bb)
58-
1. Follow usual stable point-release steps (release the LTS as `2.4.${++latest}`)
59-
60-
## Stable Release
61-
62-
### Review Commits
63-
64-
1. Ensure that all commits that are tagged for release are in the release.
65-
1. Review commits by hand since last beta was cut.
66-
1. <reminder for rwjblue to fill this in with his git cp script>
67-
1. You may run into trouble since commits are at canary, but `release` is from a branch 6 weeks ago
68-
1. @rwjblue: I have a changelog generator script that correctly links commits to PRs
69-
1. It looks at all commits on beta branch, finds the original commit where that come from, and finds the originating PR
70-
1. If I happen to run that tool again, it tells me that I have already run it so I don't accidentally run it twice
71-
1. @rwjblue: I manually scan commits looking for "bugfix beta" and cherry-pick them into the beta branch (which is imminently becoming the `release` branch)
72-
1. Automating "look for bugfix beta commits since last beta release" seems like an easy win (@tomdale)
73-
74-
### Build Changelog
75-
76-
1. Push `beta` branch to get CI to run
77-
1. Run `PRIOR_VERSION=<tag> ./bin/changelog.js | uniq | pbcopy`
78-
1. Clean up commits in CHANGELOG
79-
1. e.g. [BUGFIX beta] -> [BUGFIX], [DEPRECATE beta] -> [DEPRECATE], ...
80-
1. Remove `[DOC]` changes (who cares)
81-
1. Improve formatting (you're now in a Markdown document, so wrap code in ``s.
82-
1. Collapse all "beta" sections into final release
83-
1. E.g., commits from "beta.1", "beta.2", "beta.3" should just go under "2.4.0" or whatever
84-
1. Commit CHANGELOG
85-
86-
### Bump Version
87-
88-
1. Edit `package.json` to correct version (2.4.0)
89-
1. Edit `VERSION` file to correct value
90-
1. Seems easy to automate fixing this. Replace reading `VERSION` with reading `package.json` so you only have to change it in one place
91-
1. Commit `package.json`/`version` tags
92-
1. Add commit message: "Release v2.4.0"
93-
1. `git tag v2.4.0-ember-source`
94-
95-
### Release
96-
97-
1. `git push origin v2.4.0` to push JUST the tag. This lets us run the tag first on CI, which does the correct deploy to S3, Bower, etc.
98-
1. THEN wait for CI build to finish
99-
1. Go to github and disable branch protection for the **release** branch
100-
1. Backup the current release branch: `git push origin release:release-version`
101-
1. To make this the current `release` branch: `git push -f origin beta:release`
102-
1. This promotes the `beta` branch on your machine (that has all of the release commits) the new `release` branch on `origin`
103-
1. If you are paranoid like rojax, "freeze" this version of Ember in amber: `mv ember-beta ember-release-v2.4`
104-
1. Go to github and enable branch protection for the **release** branch
105-
106-
### Add Release on GitHub
107-
108-
1. Go to GitHub and add a new release
109-
1. Add title: `Ember 2.4`
110-
1. Copy and paste CHANGELOG
111-
112-
```
113-
# generate-api-docs.rb
114-
require 'yaml'
115-
116-
data = YAML.load_file("../components-ember/ember-docs.json")
117-
data["project"]["sha"] = ENV['VERSION']
118-
119-
File.open("data/api.yml", "w") do |f|
120-
YAML.dump(data, f)
121-
end
122-
```
123-
124-
## On to the Beta Release…
125-
126-
1. Check out `main` branch and pull to get latest `canary` on your local machine
127-
1. `nombom` and run those tests!
128-
1. Branch locally to `beta`
129-
1. `git checkout -b beta`
130-
1. Manually disable features
131-
1. Change everything in `packages/@ember/canary-features.ts`'s `DEFAULT_FEATURES` export from `null` to `false` to ensure they are stripped
132-
1. Any feature that has been GOed gets changed to true
133-
1. Run `ember s -prod`
134-
1. Run tests at `http://localhost:4200/tests/index.html`
135-
1. Run production tests `http://localhost:4200/tests/index.html?dist=prod&prod=true`
136-
1. Now we have to look at the commit just prior to branching 2.4.0.beta-1. Then find the commit after that to start the new branch at.
137-
138-
### Changelog
139-
140-
1. `PRIOR_VERSION=v2.4.0-beta.1^ HEAD=main ./bin/changelog.js | uniq | pbcopy`
141-
1. Clean up changelog. Make sure the changelog from the stable release you just did is included.
142-
143-
#### Tag & Release
144-
145-
1. Update `package.json` and `VERSION` file to use new version number
146-
1. `git tag v2.5.0-beta.1-ember-source`
147-
1. `git push origin v2.5.0-beta.1`
148-
1. `git push -f origin beta:beta`
83+
1. `git pull`
84+
1. Look for any unreleased changes on `beta` -- take note so you know what to expect in the CHANGELOG generation.
85+
1. Cherry-pick (using `git cherry-pick -x`) anything tagged `beta` that was merged to main since the last beta. To do this, look at merged PRs to find commits. The commit history isn't a good way to find these because it sorts by date, and some commits can be on old PRs that were finally merged. You may have to fix any conflicts. If this is beyond you, you can ask the original contributor to make a pull request to `beta`.
86+
1. `git push` to let CI run. You must push changes before running the CHANGELOG generation as it uses the GitHub API to find PRs.
87+
1. Generate Changelog
88+
```bash
89+
HEAD=beta PRIOR_VERSION=v5.12.0-beta.1-ember-source ./bin/changelog.js | uniq | pbcopy
90+
```
91+
1. Put the results in `CHANGELOG.md` under a heading for the new beta release. Clean up the changelog, see [Producing the CHANGELOG](#producing-the-changelog) for the details.
92+
1. Commit with message:
93+
```
94+
Add v5.12.0-beta.2 to CHANGELOG for `ember-source`
95+
```
96+
1. Update `package.json` version to:
97+
```
98+
5.12.0-beta.2
99+
```
100+
1. Commit with message:
101+
```
102+
Release v5.12.0-beta.2-ember-source
103+
```
104+
1. Tag commit:
105+
```bash
106+
git tag v5.12.0-beta.2-ember-source
107+
```
108+
1. Push tag:
109+
```bash
110+
git push origin v5.12.0-beta.2-ember-source
111+
```
112+
1. Push changes to branch `git push`
113+
1. Cherry-pick changelog commit to main branch.
114+
1. Draft release on Github, see [Creating a Release on Github](#creating-a-release-on-github).
115+
1. Wait for CI on the tag and check published to npm with `npm info ember-source`.
116+
117+
118+
### Creating a stable release
119+
120+
1. Look for any unreleased changes on `release`. If there are, consider whether there should first be a point release to the old stable version before creating a new stable release.
121+
1. In `ember.js` repo, on main branch, `git pull`.
122+
1. `git checkout beta`. (Note the branch! This is the release train).
123+
1. `git pull`.
124+
1. Cherry-pick (using `git cherry-pick -x`) anything tagged `release` that was merged to main since the last beta release. To do this, look at merged PRs to find commits. The commit history isn't a good way to find these because it sorts by date, and some commits can be on old PRs that were finally merged. You may have to fix any conflicts. If this is beyond you, you can ask the original contributor to make a pull request to `release`.
125+
1. `git push` to let CI run. You must push changes before running the CHANGELOG generation as it uses the GitHub API to find PRs.
126+
1. Generate Changelog. The `PRIOR_VERSION` should be the last beta release of the series.
127+
```bash
128+
HEAD=beta PRIOR_VERSION=v5.12.0-beta.6-ember-source ./bin/changelog.js | uniq | pbcopy
129+
```
130+
1. Put the results in `CHANGELOG.md` under a heading for the new stable release. Combine the previous `beta` headings into one entry. Clean up the changelog, see [Producing the CHANGELOG](#producing-the-changelog) for the details.
131+
1. Commit with message
132+
```
133+
Add v5.12.0 to CHANGELOG for `ember-source`
134+
```
135+
1. Update `package.json` version to:
136+
```
137+
5.12.0
138+
```
139+
1. Commit with message:
140+
```
141+
Release v5.12.0-ember-source
142+
```
143+
1. Tag commit:
144+
```bash
145+
git tag v5.12.0-ember-source
146+
```
147+
1. Push tag:
148+
```bash
149+
git push origin v5.12.0-ember-source
150+
```
151+
1. Make the `beta` branch into the `release` branch:
152+
```bash
153+
git co -B release
154+
```
155+
1. Push the new `release` branch:
156+
```bash
157+
git push -f origin release
158+
```
159+
1. Cherry-pick changelog commit to main branch.
160+
1. Draft release on Github, see [Creating a Release on Github](#creating-a-release-on-github).
161+
1. Wait for CI on the tag and check published to npm with `npm info ember-source`.
162+
1. Consider whether to tag the previous version as LTS with `npm dist-tag add [email protected] lts`. A version is tagged LTS when the next stable version is released. LTS versions are roughly every 4 versions, excluding the `x.0` minor version.
163+
1. Mark the release as complete in the Ember discord.
164+
1. Create the new beta.
165+
166+
### Creating a new beta (after a stable release)
167+
168+
1. In `ember.js` repo, on main branch, `git pull`.
169+
1. Make a new beta branch:
170+
```bash
171+
git co -B beta
172+
```
173+
1. Toggle off any features that have not been explicitly toggled on in `packages/@ember/canary-features/index.ts`.
174+
1. Find the `sha` of the last commit common to `main` and the old `beta` branch. This is typically the cherry-pick of the CHANGELOG entry.
175+
1. Generate Changelog. The `PRIOR_VERSION` is that `sha`:
176+
```bash
177+
HEAD=main PRIOR_VERSION=3daedddaafd638a4a6b12e0265df30255d1512e5 ./bin/changelog.js | uniq | pbcopy
178+
```
179+
1. Put the results in `CHANGELOG.md` under a heading for the new beta release. Clean up the changelog, see [Producing the CHANGELOG](#producing-the-changelog) for the details.
180+
1. Commit with message:
181+
```
182+
Add v5.12.0-beta.1 to CHANGELOG for `ember-source`
183+
```
184+
1. Update `package.json` version to:
185+
```
186+
5.12.0-beta.1
187+
```
188+
1. Commit with message:
189+
```
190+
Release v5.12.0-beta.1-ember-source
191+
```
192+
1. Tag commit:
193+
```bash
194+
git tag v5.12.0-beta.1-ember-source
195+
```
196+
1. Push tag:
197+
```bash
198+
git push origin v5.12.0-beta.1-ember-source
199+
```
200+
1. Push changes to branch:
201+
```bash
202+
git push -f origin beta
203+
```
204+
1. Cherry-pick changelog commit to main branch.
205+
1. Update the main branch version to the next version in package.json: `6.0.0-alpha.1` with message `Post-relase version bump`. Remember that versions go to the next major after the `x.12` release per the [Major Version Process RFC](https://rfcs.emberjs.com/id/0830-evolving-embers-major-version-process/).
206+
1. Draft release on Github, see [Creating a Release on Github](#creating-a-release-on-github).
207+
208+
### Producing the CHANGELOG
209+
[Producing the CHANGELOG]: #producing-the-changelog
210+
211+
The CHANGELOG should make sense from the perspective of a user. Remove anything that is not user-facing.
212+
The CHANGELOG entry is typically the PR title, but it can often be rewritten to be more user-friendly.
213+
Also remove the `beta` and `release` tags from the PR titles.
214+
215+
Title the CHANGELOG entry with the version and the date of the release in this format: `## v5.11.0 (August 15, 2023)`.
216+
217+
1. Remove any `[DOC]` changes (usually)
218+
1. Remove any entries for PRs that were in prior (by semver) releases
219+
1. Remove any `[INTERNAL]` changes (not user-facing). Some changes may warrant staying in the CHANGELOG, but most do not.
220+
1. `[CLEANUP]` entries may or may not be user-facing. This tag is typically used for removals of deprecated features.
221+
1. Collapse multiple PRs that were for the same issue into a single entry: `- [#12345](https://example.org/emberjs/ember.js/pull/12345) / [#67890](https://example.org/emberjs/ember.js/pull/67890) [BUGFIX] Fix an exception thrown only on Tuesdays.`
222+
1. Handle any `[FEATURE]` entries:
223+
1. If the feature is still behind a non-enabled feature flag, remove the entry.
224+
1. If the feature is now enabled by default, add an entry:
225+
1. Find the PRs that contributed to the feature.
226+
1. Link to the RFC that introduced the feature on the RFC website in the entry: `- [#20464](https://github.com/emberjs/ember.js/pull/20464) [FEATURE] Create public import for uniqueId helper per [RFC #659](https://rfcs.emberjs.com/id/0659-unique-id-helper).`
227+
1. Change `[BUGFIX beta]` `[BUGFIX release]` `[BUGFIX stable]` to `[BUGFIX]`
228+
1. Change `[DEPRECATION beta]` `[DEPRECATION release]` `[DEPRECATION stable]` to `[DEPRECATION]`
229+
1. Handle any other PR or commit tags similarly.
230+
231+
### Creating a Release on Github
232+
[Creating a Release on Github]: #creating-a-release-on-github
233+
234+
1. Go to the [Ember.js releases page](https://github.com/emberjs/ember.js/releases)
235+
2. Click the "Draft a new release" button
236+
3. Choose the tag of the release you just created
237+
4. Title the release with the name of the tag `v5.11.0-ember-source` (or whatever the version is).
238+
5. Add a header to the description of `### CHANGLEOG`.
239+
6. Copy the CHANGELOG entry for the version below this header.
240+
7. Check 'Pre-release' if this is not a stable release.
241+
8. Choose `Set as the latest release` only if this is the latest stable release. Do not check this for the release of a point release on an older version.

0 commit comments

Comments
 (0)