From bbe0b0384b2ed1d86568ede1187e36ae59a9a556 Mon Sep 17 00:00:00 2001 From: Gary Yu Date: Wed, 26 Sep 2018 04:14:10 +0800 Subject: [PATCH] docs: add release instruction (#1571) --- CONTRIBUTING.md | 16 +++++ doc/release_instruction.md | 134 +++++++++++++++++++++++++++++++++++++ doc/table_of_contents.md | 1 + 3 files changed, 151 insertions(+) create mode 100644 doc/release_instruction.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df945845f..6a14a0b6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,22 @@ If any help is needed during your effort to contribute on this project, please d * Mailing list: join the [~MimbleWimble team](https://launchpad.net/~mimblewimble) and subscribe on Launchpad. * News: [Twitter](https://twitter.com/grinmw). Twitter bot that scrapes headlines, mailing list, and reddit posts related to MimbleWinble/Grin. +# Pull-Request Title Prefix + +**Note**: *[draft part! to be reviewed and discussed]* + +Please consider putting one of the following prefixes in the title of your pull-request: +- **feat**: A new feature +- **fix**: A bug fix +- **docs**: Documentation only changes +- **style**: Formatting, missing semi-colons, white-space, etc +- **refactor**: A code change that neither fixes a bug nor adds a feature +- **perf**: A code change that improves performance +- **test**: Adding missing tests +- **chore**: Maintain. Changes to the build process or auxiliary tools/libraries/documentation + +For example: `fix: a panick on xxx when grin exiting`. Please don't worry if you can't find a suitable prefix, this's just optional, not mandatory. + # Grin Style Guide Grin uses `rustfmt` to maintain consistent formatting, and we're using the git commit hook as explained below. diff --git a/doc/release_instruction.md b/doc/release_instruction.md new file mode 100644 index 000000000..79dfa6bee --- /dev/null +++ b/doc/release_instruction.md @@ -0,0 +1,134 @@ +# Grin - Instruction of Release + +**Note**: *[totally draft doc! to be reviewed and discussed]* + +## Version Number Rule + +In Grin, we're using [Semantic Versioning 2.0.0](https://semver.org). For a short description of the rule: + +A version number include MAJOR.MINOR.PATCH, and increment the: +1. MAJOR version when you make incompatible API changes, +2. MINOR version when you add functionality in a backwards-compatible manner, and +3. PATCH version when you make backwards-compatible bug fixes. +And **additional labels for pre-release** and **build metadata** are available as extensions to the MAJOR.MINOR.PATCH format. + +The examples of the release version of Grin: +- 0.3.0 +- 0.3.1 +- 1.5.90 + +The examples of **label of pre-release**: +- 1.0.0-alpha.1 +- 1.0.0-beta.2 +- 1.0.0-test.5 + +In Grin, **build metadata** is used as the build number which comes from the Travis-CI job ID of building jobs, it's an unique ID for each building. **Note**: for the moment, this metadata is only used in the name of the released binary, and it's auto generated, no need to set it manually. + +Here is an example of the build metadata of Grin release version: +- 0.3.1-430839304 + +And as the end of this section, here's an example of the whole encoded version string: +- 0.3.1-pre.1-430839316 + +## Release Files (Binaries) + +So far, Grin support both Mac and Linux, and 64bits only. There're 2 binaries in one version release, plus md5 checksum for each binary. + +For example: +- grin-0.3.1-pre.1-430839316-oxs.tgz +- grin-0.3.1-pre.1-430839316-oxs.tgz-md5sum.txt +- grin-0.3.1-pre.1-430839318-linux-amd64.tgz +- grin-0.3.1-pre.1-430839318-linux-amd64.tgz-md5sum.txt + + +## Change Log of Release + +Currently, Grin release is using automatic change log generating, thanks to [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator). These change logs are fully automated generated, and normally there's no human editing on these change logs, but in case of any exception display on release page, we could do a little manual fixing on that. + +The github changelog generator heavily rely on the Github project **issues*, **pull requests**, so for achieving a good change log on each release, we have to follow some rules on the daily management of github **issues** and **pull request**. + +And this changelog generator will collect all the github closed issues and merged pull-requests, **since last tag**. + +Also it will give a link to fully compare this release with the previous tag in github. + +## Rules of Github Issue and Pull-Request Management + +As said above, we have to define some basic rules for github issue and pull-request, but don't worry, it's quite simple! + +### Rules of Issue + +The most important rule is to Distinguish Issues by **Labels**: + +- Label bug issues as **bug** +- Label enhancement issues as **enhancement** + +And all closed issues w/o label will be put into group "closed issues with no labels", which is definitely not so good. + +As opposite, all closed issues with the following labels will be automatically excluded from the change log: + +- **question** +- **duplicate** +- **invalid** +- **wontfix** + +For more details, please run `github_changelog_generator --help`, or check its github repo: https://github.com/github-changelog-generator/github-changelog-generator + +### Rules of Pull-Request + +And regarding to merged **pull-requests**, it will be put into group "all merged pull-requests". And it's strongly recommended that each pull-request give a commit message with prefix: +- **feat**: A new feature +- **fix**: A bug fix +- **docs**: Documentation only changes +- **style**: Formatting, missing semi-colons, white-space, etc +- **refactor**: A code change that neither fixes a bug nor adds a feature +- **perf**: A code change that improves performance +- **test**: Adding missing tests +- **chore**: Maintain. Changes to the build process or auxiliary tools/libraries/documentation + +These prefix are part of [Angular.js commit message conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit?pref=2&pli=1#heading=h.uyo6cb12dt6w), and you can take a look at the practice in [Angular.js github project](https://github.com/angular/angular.js/commits/master). + +There's no need to fully follow Angular.js commit message conventions. We just need use these prefix in each pull-request's commit message, that's all. Perhaps a simple **pull-request template** can be set as default in Github. + +## Release Branches + +Each time when Grin release a new version, there's definitely a tag there with same version number. But it's not mandatory to have a **branch** with this version release. + +We define the following rules for the **release branch**: +1. Only **MAJOR.MINOR** version could have a release branch, but also NOT mandatory. +2. Only when a fix is needed for a **MAJOR.MINOR** version, we create a **release branch** on the name of **MAJOR.MINOR** from the tag of **MAJOR.MINOR.0**, and only one branch for all the fixes on this **MAJOR.MINOR** version. +3. New version based on this **release branch** must have same **MAJOR.MINOR** version number, only **.PATCH** can be changed. + +## Release Instruction + +### 1. TAG + +To trigger a version release, the ONLY thing which need to do manually is to make a tag. As the **owner** of a github repo, he/she just need to run 2 commands locally: +``` +git tag 0.3.1-pre1 -m "0.3.1 pre release 1" +git push origin 0.3.1-pre1 +``` +Done. +Remember to replace `0.3.1-pre1` as the real version, and warmly remind the [[Version Number Rule]]. For official release, just use `0.3.1` or something like that. + +If you're NOT the owner of the github repo, but at least you have to be a committer which has the right to do a release, the following steps are needed to trigger a version release: +1. Go to release page of the repo, click **Draft a new release**, remember to check the branch is what you're working on! set the **Tag version** to the release number (for example: `0.3.1-pre1`), and set anything in **Release title** and **description**, then click **Publish release**. Don't worry the title and description parts because we need delete it in next step. +2. Because github **release** will be auto-created by our `auto-release` building script, we MUST delete the **release** which we just created in previous step! (Unfortunately, there's no way to only create **tag** by web.) + +Even normally Travis-CI need tens of minutes to complete building, I suggest you complete step 2 quickly, otherwise the `auto-release` script will fail on error "release already exist". + +### 2. Travis-CI Building + +For building in both mac and Linux, we enabled the CI on both platforms, since we start doing this automatic binaries release. + +The release building is just one of the **TEST_DIRS**, named as `none`. So each time when version release building is triggered, all those exising Travis-CI tests are also triggered, this design is for the CI test purpose and we hope this new added auto release script has no any impact on these existing CI tests. + +So, the point is: the release building job is that one tagged with `TEST_DIR=none`. + +Note: `auto-release` script will only be executed on `deploy` stage, and according to Travis-CI, it will be skipped for any **pull-request** trigger, and since we set `tag: true` it will be only executed when triggered by a tag. + + +### 3. Check the Release Page + +The last step is to check the Github release page, after Travis-CI complete the whole building, normally it need half an hour or one hour. + + diff --git a/doc/table_of_contents.md b/doc/table_of_contents.md index 631db8bc7..1afc183d1 100644 --- a/doc/table_of_contents.md +++ b/doc/table_of_contents.md @@ -19,6 +19,7 @@ ## Build and use - [build](build.md) - Explaining how to build and run the Grin binaries +- [release](release_instruction.md) - Instructions of making a release - [usage](usage.md) - Explaining how to use grin in Testnet3 - [wallet](wallet/usage.md) - Explains the wallet design and `grin wallet` sub-commands