From 1c0043a5645ab0cfb37e097a4a1d70495f3082f8 Mon Sep 17 00:00:00 2001 From: Develo Date: Wed, 12 Dec 2018 01:20:58 -0300 Subject: [PATCH 1/4] Update README.md Fix json url typo Clarify some points Add readthedocs instructions --- package/README.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/package/README.md b/package/README.md index 917a3ed34f..787c24912b 100644 --- a/package/README.md +++ b/package/README.md @@ -57,35 +57,42 @@ Here is an overview of the release process. See the section below for detailed i * When done, put release notes into a private Gist and send the link to other maintainers for review. - * Update `version` to the release in platform.txt and commit. E.g. `2.5.0`. +The following points assume work in a direct clone of the repository, and not in a personal fork. -2. Tag the latest commit on the master branch. 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. Update `version` to the release in platform.txt and commit. E.g. `2.5.0`. Then git push origin to get the commit merged to master. + +3. Tag the latest commit on the master branch. 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 + git tag -a -m "Release 2.5.0" 2.5.0 ``` -3. Push the tag created in step 2 to esp8266/Arduino Github repository: +4. Push the tag created in step 2 to esp8266/Arduino Github repository: ``` - git push origin 2.4.0 + git push origin 2.5.0 ``` -4. 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. +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. + +6. Check that the package index downloaded from http://arduino.esp8266.com/stable/package_esp8266com_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, and publish it. -5. 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). +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. 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. +9. 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 and trigger it manually. -7. 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. -8. Create a commit to the master branch, updating: +10. Create a commit to the master branch, updating: * 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. - - in "Latest release" section, change version number in the readthedocs link to the version which was just released. + - Replace any other instances of the version number in the doc. + + - Check that links to the latest readthedocs build are correct. + From 7c04fac146ebb43779609cf2bc7a32f37bf26c7e Mon Sep 17 00:00:00 2001 From: Develo Date: Wed, 12 Dec 2018 02:05:16 -0300 Subject: [PATCH 2/4] Update README.md Rephrase --- package/README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/package/README.md b/package/README.md index 787c24912b..cd9a099bc0 100644 --- a/package/README.md +++ b/package/README.md @@ -90,9 +90,4 @@ The following points assume work in a direct clone of the repository, and not in * In main README.md: - - in "Latest release" section, change version number in the readthedocs link to the version which was just released. - - - Replace any other instances of the version number in the doc. - - - Check that links to the latest readthedocs build are correct. - + - in "Latest release" section, change version number in the readthedocs link to the version which was just released, and verify that all links work. From bfc6dff9086f579420a1397520a11ae9a718634b Mon Sep 17 00:00:00 2001 From: Develo Date: Thu, 13 Dec 2018 11:25:54 -0300 Subject: [PATCH 3/4] Update README.md Incorporate feedback --- package/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package/README.md b/package/README.md index cd9a099bc0..4e71da343c 100644 --- a/package/README.md +++ b/package/README.md @@ -61,7 +61,7 @@ The following points assume work in a direct clone of the repository, and not in 2. Update `version` to the release in platform.txt and commit. E.g. `2.5.0`. Then git push origin to get the commit merged to master. -3. Tag the latest commit on the master branch. 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): +3. Tag the latest commit on the master branch. In this project, tags have form `X.Y.Z`, e.g. `2.4.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 2.5.0" 2.5.0 From 977da255cd64c3f501044971aa2f052d0368acf9 Mon Sep 17 00:00:00 2001 From: Develo Date: Thu, 13 Dec 2018 11:48:20 -0300 Subject: [PATCH 4/4] Update README.md Added Release model section --- package/README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/package/README.md b/package/README.md index 4e71da343c..206b4664d3 100644 --- a/package/README.md +++ b/package/README.md @@ -1,5 +1,35 @@ # Release tools +## Release model + +The release model is linear. That means that there is only one main code branch, and releases are snapshots of that branch at specific points in the sequence of commits. +The advantage of this model is that the maintenance effort is greately reduced compared to other release models, such as a branched model. +The disadvantage is that progress is ever only forward, and fixes can't be backported to prior releases. this means there is no such thing as a "stable" release (however, see Sub releases below). + +There are 4 types of releases: + +*Major releases* + +These contain breaking changes, such as big API changes, both in function signature and data representation. When this happens, user apps will require changes to continue to work, and those changes could be significant. +Major releases happen seldom, e.g.: every few years. +In addition, a Major can contain changes from Minor releases. + +*Minor releases* + +These contain new features and bug fixes. Breaking changes should not be included here. The one exception is breaking changes for a feature that is too broken and is not worth fixing, especially if that feature is causing maintenance overhead. +Minor releases happen maybe 1-3 times per year. +In addition, a Minor release can contain changes from Sub releases. + +*Sub releases* + +Sub releases are mostly meant for stabilization purposes. Once a Major or Minor release is out, it is possible that critical bugs or issues are found. Given that fixes can't be backported, a sub release is made that includes such critical bug fixes. +Sub releases happen a few weeks after a Major or Minor release. + +*Beta releases* + +Depending on the number of changes that have been merged since the last release, and on how big and disruptive those changes are, a beta release could be done prior to a Major or Minor. Beta releases are meant to provide an outlook of what the upcoming release will look like, in order to allow users to do early testing and provide feedback. This helps in identifying big issues early on, thereby allowing time to fix them before the final Major or Minor release. +Beta releases should not be done for Sub releases. + ## Overview This directory contains scripts used to automate the release process of esp8266/Arduino project.