Update release instructions (#7292)

* Update release instructions to reflect reality, add copy-paste checklist to ease issue.

Author: devyte

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--------------
+```