diff --git a/package/README.md b/package/README.md index 76157a4209..b9bbdcfe6e 100644 --- a/package/README.md +++ b/package/README.md @@ -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. + + +## 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-------------- +```