Minor fixes for #4999 (#5003)

* ci: work around tagging issue in Travis CI deployment

When `draft: true` is set, incorrect commit/tag information is sent to
Github. Override tag/target fields for correct behavior.

Ref. https://github.com/travis-ci/travis-ci/issues/9852

* doc: clarify some points in the release process

Author: igrr

.travis.yml

@@ -50,6 +50,8 @@ deploy:
     api_key:
       secure: A4FBmqyhlzy33oPeZVolg2Q/A3ZcJ3WnRQqQJ3NAPy+qGM5xcboOYtwcLL9vKaHZGfUB7lUP9QVZFGou1Wrmo9DnPvAoe3+XvCaDRGzVMxeIpu7UStbBD4Knbh98tlbMvZCXYRlT4VcusI9bMLK6UWw4sMdPislBh2FEfglTiag=
     file_glob: true
+    tag_name: $TRAVIS_TAG
+    target_commitish: $TRAVIS_COMMIT
     file:
       - package/versions/$TRAVIS_TAG/esp8266-$TRAVIS_TAG.zip
       - package/versions/$TRAVIS_TAG/package_esp8266com_index.json

package/README.md

@@ -11,7 +11,7 @@ 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.
+Here is an overview of the release process. See the section below for detailed instructions.
 
 1. Release process starts when a maintainer pushes a tag into the repository.
 
@@ -51,29 +51,43 @@ Here is an overview of the release process.
 
    * 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 issues which have been introduced since last release.
+   * 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.
 
-2. Tag the latest commit. In this project, tags have form `X.Y.Z`, e.g. `2.4.0`, or `X.Y.Z-rcN` for release 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):
+2. Create a commit on the master branch, making the following changes:
+
+   * Set version in platform.txt to the version about to be released. E.g. change from `2.4.0-dev` to `2.4.0`
+
+   * In main README.md, in "Latest release" section, change version number in the readthedocs link to the version which is about to be created.
+
+   * Commit message should be `Release X.Y.Z`
+
+3. Tag the commit created in step 2. In this project, tags have form `X.Y.Z`, e.g. `2.4.0`, or `X.Y.Z-rcN` for release 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 2.4.0" 2.4.0
    ```
-   
-   Push the tag to esp8266/Arduino Github repository.
 
+4. Push the commit created in step 2 and the tag created in step 3 to esp8266/Arduino Github repository:
+
+   ```
+   git push origin --follow-tags master
+   ```
+
+5. Wait for Travis CI build for the tag to pass. Check that the new (draft) release has been created. Check that the boards manager package .zip file has been successfully uploaded as a release artifact.
 
-3. Wait for Travis CI build for the tag to pass. Check that the new (draft) release has been created. Check that the boards manager package .zip file has been successfully uploaded as a release artifact.
+6. Check that the package index downloaded from http://arduino.esp8266.com/stable/package_esp8266_index.json contains an entry for the new version (it may not be the first one).
 
-4. Check that the package index downloaded from http://arduino.esp8266.com/stable/package_esp8266_index.json contains an entry for the new version (it may not be the first one).
+7. Navigate to release list in Github, press "Edit" button to edit release description, paste release notes. Remove "draft" status of the release and publish it.
 
-5. Navigate to release list in Github, press "Edit" button to edit release description, paste release notes. Remove "draft" status of the release and publish it.
+8. 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.
 
-6. 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.
+9. Create a commit to the master branch, updating:
 
-7. Make a commit to master branch, updating the version in platform.txt file. This should correspond to the version of the *next* milestone.
+   * The version in platform.txt file. This should correspond to the version of the *next* milestone, plus `-dev` suffix. E.g. `2.5.0-dev`.
 
+   * In main README.md, in "Contributing" section, update the "easy issues" link to point to the next milestone.