From 485eb7810012c3ce0025f80d647537a1b850dce8 Mon Sep 17 00:00:00 2001 From: Avi Kelman Date: Mon, 18 May 2020 18:40:22 -0400 Subject: [PATCH] :pencil: Populate readme --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c57640a..9089254 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,63 @@ -# d3b-release-maker -Tool to generate GitHub-based software releases +# D3b Release Maker + +Tool to automate GitHub-based software releases for projects with the following +characteristics: + +- Feature branching with merge-commits into master +- Gitmoji-style PR messages +- Semantic versioning tags for releases () + +## Part 1: CLI that generates release notes and creates a PR on GitHub for review + +Install with pip: +`pip install git+https://github.com/d3b-center/d3b-release-maker.git` + +Create a temporary auth token on GitHub and add it to your environment as +`GH_TOKEN`. + +Then run: `release --help` + +## Part 2: GitHub Action that automates tagging releases and asset uploading + +Copy `.github/workflows/gh_releases.yml` into the same location in your +repository. (Read more about GitHub Actions at ) + +If you want to attach binary assets to your GitHub releases, add a +`.github/prepare_assets.sh` script that generates your assets and +then creates `.github/release_assets.txt` containing a list of the files you +want to upload, one per line, in the order that you want them to appear. + +## What the parts do + +### What the CLI does + +When you run the `release build` command: + +1. The CLI looks at the most recent git tag that looks like a Semantic Version. +2. Then it looks for all PRs that were merged into master after that tag which + do not themselves look like a release merge. +3. Emojis at the start of the PR titles are grouped and counted according to + the gitmoji emoji guide (). +4. Markdown is generated with links to PRs, merge commits, and committers and is + shown to the user. +5. The user is prompted to provide a type of version update (major, minor, + patch) based on the shown list of changes, and a new version number is + generated. +6. A fresh copy of your repository is cloned to a temporary location. +7. The new changes list is added to the CHANGELOG.md file (one is created if + one doesn't already exist). +8. An optional user-provided script is then run if you need to e.g. add the new + version number to files in your repository. +9. All newly modified files are commited with a special release commit and + pushed to a special release branch, and a Pull Request into master is opened + on GitHub for review. + +### What the GitHub Action does + +When a special release branch is merged into master: + +1. Your repository is tagged with the new semantic version, and a GitHub + release is created with the contents of the just-merged Pull Request body. +2. If a `.github/prepare_assets.sh` script exists, it is run. +3. If a `.github/release_assets.txt` file exists, any files listed in it are + then uploaded to the GitHub release.