arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-06-03 07:02:28 +03:00
Code

Update release instructions (#7292)

Browse Source 
* Update release instructions to reflect reality, add copy-paste checklist to ease issue.
This commit is contained in:
Develo 2020-05-10 21:48:38 -04:00 committed by GitHub
parent 56bbb99e6f
commit 7f3d837e57
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 74 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
package/README.md
View File

@ -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`.
@ -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.
@ -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
@ -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.
- in "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)
- [ ] 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--------------
```