D3b Release Maker

Tool to automate GitHub-based software releases for projects with the following characteristics:

Feature branching with merge-commits into your default branch
Gitmoji-style PR messages
Semantic versioning tags for releases (https://semver.org)

Part I: Changes Needed In Your Repository

Step 1: Add the GitHub Actions Workflow to your project repository

This automates tagging releases and asset uploading when a new release PR is merged.

Copy gh_releases.yml from this repository's .github/workflows/ directory into .github/workflows/ in your project repository. (Read more about GitHub Actions and Workflows at https://help.github.com/en/actions)

If you want to attach binary assets to your GitHub releases, add a .github/prepare_assets.sh script that receives one input argument with the new release version and generates your assets and then optionally 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.

Step 2 (optional): Add release_cfg.json to your project repository

Add a release_maker_cfg.json file to your repository's default branch. Its contents should be as follows:

{
  "project_title": "Your Repository Project Title",
  "pre_release_script": "script/to/run/before/making/release/PR.sh"
}

If you skip this step, the file will be automatically added during the next release after prompts from the release maker CLI tool.

Step 3 (for Python setuptools packages): Tie package version to repository metadata

If your repository is a Python setuptools package, you can tie the package version to the repository release version so that you don't need to separately store the version in a file. The easiest way to do that is with the setuptools_scm package.

If your project uses a setup.py file, do this instead of explicitly stating a version:

from setuptools import setup

setup(
    use_scm_version={
        "local_scheme": "dirty-tag",
        "version_scheme": "post-release",
    },
    setup_requires=["setuptools_scm"],
    ...
)

See https://github.com/d3b-center/d3b-release-maker/blob/main/setup.py for an example.

If you use one of the other setuptools configuration methods (e.g. pyproject.toml), read https://github.com/pypa/setuptools_scm/ for the equivalent of the above.

Part II: The CLI that updates release notes and creates a GitHub release PR

Step 1: Install the CLI tool

Install the latest release of the release maker with pip:

pip install --upgrade git+https://github.com/d3b-center/d3b-release-maker.git@latest-release
Create an authentication token on GitHub at https://github.com/settings/tokens

The release tool CLI will prompt you to enter your token when needed, or you can populate a GH_TOKEN environment variable and then it won't prompt you unless the stored token is invalid.

For public repositories, you only need to grant the "public_repo" authorization scope.

For private repositories, the token needs the full "repo" scope.

Step 2: Run the CLI tool

Run release preview to explore what running the tool is like.

Run release build to actually do the release.

Step 3: Review and merge the PR

The CLI tool creates a special release PR for everyone to review. When it's approved and merged, the GitHub Actions workflow finalizes the release.

What the parts do

What the GitHub Actions Workflow does

When a special release branch is merged into the default branch:

Your repository is tagged with the new semantic version and also a rolling tag called 'latest-release' for use with pip, and a GitHub release is created with the contents of the just-merged Pull Request body.
If a .github/prepare_assets.sh script exists, it is run.
If a .github/release_assets.txt file exists, any files listed in it are then uploaded to the GitHub release.

What the setuptools modification does

It uses the repository's semantic version release tags as the Python package version instead of needing to separately store the version somewhere in the repository files.

What the CLI does

When you run the release build command:

The CLI looks at the most recent git tag that looks like a Semantic Version.
Then it looks for all PRs that were merged into the default branch after that tag which do not themselves look like a release merge.
Emojis at the start of the PR titles are grouped and counted according to the gitmoji emoji guide (https://gitmoji.carloscuesta.me).
Markdown is generated with links to PRs, merge commits, and committers and is shown to the user.
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.
A fresh copy of your repository is cloned to a temporary location.
The new changes list is added to the CHANGELOG.md file (one is created if one doesn't already exist).
An optional user-provided script is then run if you need to e.g. add the new version number to files in your repository.
All newly modified files are commited with a special release commit and pushed to a special release branch, and a Pull Request into the default branch is opened on GitHub for review.

Github Token Auth Scope

in the readme:

If you only want to release public repositories, you don't need to grant the token any authorization scopes. If you want to release private repositories as well, the token needs the "repo" scope.

Does this still hold true?

I just tried using the release maker on a public repo with a github token that i did not grant an authorization scope to and got the error below:

Traceback (most recent call last):
  File "/Users/chris/dotfiles/venv/bin/release", line 33, in <module>
    sys.exit(load_entry_point('d3b-release-maker==2.1.0', 'console_scripts', 'release')())
  File "/Users/chris/dotfiles/venv/lib/python3.9/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/Users/chris/dotfiles/venv/lib/python3.9/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/Users/chris/dotfiles/venv/lib/python3.9/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/chris/dotfiles/venv/lib/python3.9/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/chris/dotfiles/venv/lib/python3.9/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/Users/chris/dotfiles/venv/lib/python3.9/site-packages/d3b_release_maker/cli.py", line 64, in make_release_cmd
    make_release(repo, blurb_file)
  File "/Users/chris/dotfiles/venv/lib/python3.9/site-packages/d3b_release_maker/release_maker.py", line 557, in make_release
    subprocess.run(
  File "/usr/local/Cellar/[email protected]/3.9.6/Frameworks/Python.framework/Versions/3.9/lib/python3.9/subprocess.py", line 528, in run
    raise CalledProcessError(retcode, process.args,
subprocess.CalledProcessError: Command '['git', 'push', '--force', 'origin', 'release-0.1.0-🏷']' returned non-zero exit status 128.

After giving the same token repo auth scope, the release worked.

My guess is that tokens being used to run the release maker on public repositories need - minimally - repo >> public_repo authorization.

d3b-center / d3b-release-maker Goto Github PK