mirror of
https://github.com/mimblewimble/grin.git
synced 2025-01-20 19:11:08 +03:00
docs: add release instruction (#1571)
This commit is contained in:
Gary Yu
Ignotus Peverell
parent
11f2d7b6d4
commit
bbe0b0384b
3 changed files with 151 additions and 0 deletions
|
|
@ -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.
|
||||
|
|
|
|||
134
doc/release_instruction.md
Normal file
134
doc/release_instruction.md
Normal file
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue