Skip to content

Update release instructions #7292

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

Merged
merged 2 commits into from
May 11, 2020
Merged

Update release instructions #7292

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f50d25a
Update release instructions
devyte May 11, 2020
10f9810
Update README.md
devyte May 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 74 additions & 22 deletions package/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ The purpose of the release process is to generate the following outputs from the

* Github Release for esp8266/Arduino project. This is used to host the boards manager package mentioned above, and also contains the release notes.

Here is an overview of the release process. See the section below for detailed instructions.
Here is a rough overview of the effective release process. See the section below for detailed instructions.

1. Release process starts when a maintainer pushes a tag into the repository.
1. Release process effectively starts when a maintainer pushes a tag into the repository.

2. Travis CI runs a build for this tag, and one of the jobs (with `BUILD_TYPE=package`) is used to prepare the boards manager package. This job runs `build_boards_manager_package.sh`.

Expand All @@ -65,9 +65,11 @@ Here is an overview of the release process. See the section below for detailed i

## Creating a release (for maintainers)

0. Open a new issue to track activities, which will be closed after the release is done.
1. [Open a new issue](https://github.com/esp8266/Arduino/issues/new/choose) to track activities, which will be closed after the release is done. Copy the checklist below into it, and check the steps one by one as they get completed.

1. Assemble release notes.
2. Make sure that no issues or PRs are assigned to the milestone to be released. If there are any Issues/PRs assigned to the relevant milestone, they should either be addressed, pushed back to a future milestone, or closed.

3. Assemble release notes.

* Since most changes are integrated into master using squash-rebase policy (i.e. one commit per PR), `git log --oneline` gives a good overview of changes in the release.

Expand Down Expand Up @@ -99,22 +101,24 @@ Here is an overview of the release process. See the section below for detailed i

* Not all commit descriptions which come from `git log` will explain changes well. Reword items as necessary, with the goal that a general user of this project should be able to understand what the change is related to. Preserve references to PRs or issues (`#XXXX`).

* Don't include fixes for regressions which have been introduced since last release.

* Aggregate minor fixes (e.g. typos, small documentation changes) in a few items. Focus on preparing a good overview of the release for the users, rather than mentioning every change.

* When done, put release notes into a private Gist and send the link to other maintainers for review.
* When done, put release notes into a private [Gist](https://gist.github.com) or [firepad](https://demo.firepad.io) and send the link to other maintainers for review.

The following points assume work in a direct clone of the repository, and not in a personal fork.

2. Make a PR with the following, wait for Travis CI, and merge.
4. Make a PR with the following, [wait for Travis CI](https://travis-ci.org/github/esp8266/Arduino/builds/), and merge.

* platform.txt and package.json: update `version` to the release E.g. `3.0.0`,
* [platform.txt](https://github.com/esp8266/Arduino/blob/master/platform.txt) and [package.json](https://github.com/esp8266/Arduino/blob/master/package.json): update `version` to the release E.g. `3.0.0`,

* `cores/esp8266/TZ.h`: import the latest database with the following shell command:\
* [cores/esp8266/TZ.h](https://github.com/esp8266/Arduino/blob/master/cores/esp8266/TZ.h): import the latest database with the following shell command:\
`$ cd tools; sh TZupdate.sh`.

3. Tag the latest commit on the master branch. In this project, tags have form `X.Y.Z`, e.g. `3.0.0`, or `X.Y.Z-betaN` for release candiate versions. Notice that there's no `v`at the beginning of the tag. Tags must be annotated, not lightweight tags. To create a tag, use git command (assuming that the master branch is checked out):
5. Wait until the release notes have been checked by other maintainers

6. Navigate to [Travis CI options](https://travis-ci.org/esp8266/Arduino/settings), enable ´Build pushed branches´ (before tagging in next step)

7. Tag the latest commit on the master branch. In this project, tags have form `X.Y.Z`, e.g. `3.0.0`, or `X.Y.Z-betaN` for release candiate versions. Notice that there's no `v`at the beginning of the tag. Tags must be annotated, not lightweight tags. To create a tag, use git command (assuming that the master branch is checked out):

```
git tag -a -m "Release 3.0.0" 3.0.0
Expand All @@ -128,30 +132,78 @@ The following points assume work in a direct clone of the repository, and not in
git push origin 3.0.0
```

4. In case something goes wrong, release can be canceled at any time:
In case something goes wrong, release can be canceled at any time:

* Tag must be removed (`git tag -d X.Y.Z; git push --delete origin X.Y.Z`)

* Release must be deleted: github > releases > edit x.y.z > remove all files > delete button appears

5. Wait for Travis CI build for the tag to pass, see https://travis-ci.org/esp8266/Arduino/builds,
8. Wait for Travis CI build for the tag to pass, see https://travis-ci.org/esp8266/Arduino/builds,

return to the Travis CI options and disable `Build pushed branches`.

6. Check that the new (draft) release has been created (no editing at this point!), see https://github.com/esp8266/Arduino/releases. Check that the boards manager package .zip file has been successfully uploaded as a release artifact.
9. Check that the new (draft) release has been created (no editing at this point!), see https://github.com/esp8266/Arduino/releases.

7. Check that the package index downloaded from https://arduino.esp8266.com/stable/package_esp8266com_index.json contains an entry for the new version (it may not be the first one).
10. Check that the boards manager package .zip file has been successfully uploaded as a release artifact.

8. Navigate to release list in Github here https://github.com/esp8266/Arduino/releases, press "Edit" button to edit release description, paste release notes, and publish it.
11. Check that the package index downloaded from https://arduino.esp8266.com/stable/package_esp8266com_index.json contains an entry for the new version (it may not be the first one).

9. In the issue tracker, remove "staged-for-release" label for all issues which have it, and close them. Close the milestone associated with the released version.
12. Return to the [Travis CI options](https://travis-ci.org/esp8266/Arduino/settings) and disable `Build pushed branches`.

10. Check that https://arduino-esp8266.readthedocs.io/en/latest/ has a new doc build for the new tag, and that "stable" points to that build. If a new build did not trigger, log into readthedoc's home here https://readthedocs.org/ (account must have been added to project as maintainer) and trigger it manually.
13. Navigate to release list in Github here https://github.com/esp8266/Arduino/releases, press "Edit" button to edit release description, paste release notes, and publish it.

11. Create a commit to the master branch, updating:
14. In the issue tracker, remove "staged-for-release" label for all issues which have it, and close them. Close the milestone associated with the released version (the milestone should be empty per point 2 above)

15. Check that https://arduino-esp8266.readthedocs.io/en/latest/ has a new doc build for the new tag, and that "stable" points to that build. If a new build did not trigger, log into readthedoc's home here https://readthedocs.org/ (account must have been added to project as maintainer) and trigger it manually.

16. Create a commit to the master branch, updating:

* The version in platform.txt and package.json files. This should correspond to the version of the *next* milestone, plus `-dev` suffix. E.g. `3.1.0-dev`.

* In main README.md:
* In main README.md go to "Latest release" section, change version number in the readthedocs link to the version which was just released, and verify that all links work.


## Checklist helper, copy-paste into Release Process issue
```
--------------COPY BELOW THIS LINE--------------
[Reference](https://github.com/esp8266/Arduino/tree/master/package#creating-a-release-for-maintainers) for details.

- [ ] 1. Open a new issue to track activities.

- [ ] 2. Make sure that no issues or PRs are assigned to the milestone to be released.

- [ ] 3. Assemble release notes.

- [ ] 4. Make a PR with the following, [wait for Travis CI](https://travis-ci.org/github/esp8266/Arduino/builds/), and merge.

* [platform.txt](https://github.com/esp8266/Arduino/blob/master/platform.txt)
* [package.json](https://github.com/esp8266/Arduino/blob/master/package.json)
* [cores/esp8266/TZ.h](https://github.com/esp8266/Arduino/blob/master/cores/esp8266/TZ.h)

- in "Latest release" section, change version number in the readthedocs link to the version which was just released, and verify that all links work.
- [ ] 5. Wait until the release notes have been checked by other maintainers

- [ ] 6. Navigate to [Travis CI options](https://travis-ci.org/esp8266/Arduino/settings), enable ´Build pushed branches´ (before tagging in next step)

- [ ] 7. Tag the latest commit on the master branch, then push it to esp8266/Arduino

- [ ] 8. Wait for Travis CI build for the tag to pass, see https://travis-ci.org/esp8266/Arduino/builds,

- [ ] 9. Check that the new (draft) release has been created (no editing at this point!), see https://github.com/esp8266/Arduino/releases.

- [ ] 10. Check that the boards manager package .zip file has been successfully uploaded as a release artifact.

- [ ] 11. Check that the package index downloaded from https://arduino.esp8266.com/stable/package_esp8266com_index.json contains an entry for the new version (it may not be the first one).

- [ ] 12. Return to the [Travis CI options](https://travis-ci.org/esp8266/Arduino/settings) and disable `Build pushed branches`.

- [ ] 13. Navigate to [release list in Github](https://github.com/esp8266/Arduino/releases), press "Edit" button to edit release description, paste release notes, and publish it.

- [ ] 14. In the issue tracker, remove "staged-for-release" label for all issues which have it, and close them. Close the milestone associated with the released version (the milestone should be empty per point 2 above)

- [ ] 15. Check that https://arduino-esp8266.readthedocs.io/en/latest/ has a new doc build for the new tag, and that "stable" points to that build. If a new build did not trigger, log into readthedoc's home here https://readthedocs.org/ (account must have been added to project as maintainer) and trigger it manually.

- [ ] 16. Create a commit to the master branch, updating:

* The version in platform.txt and package.json files. This should correspond to the version of the *next* milestone, plus `-dev` suffix. E.g. `3.1.0-dev`.
* In main README.md go to "Latest release" section, change version number in the readthedocs link to the version which was just released, and verify that all links work.
--------------COPY ABOVE THIS LINE--------------
```