This is a command-line tool to retrieve the list of stories from the Shortcut issue tracker which will be deployed in a release, and generate release notes based on a template.

graph TD
    A(fa:fa-code-branch Scan commits)--> B(fa:fa-download Get stories)
    B --> C(fa:fa-download Get epics)
    C -->D(fa:fa-file Build Markdown release notes)

For each repository listed in its configuration file, it scans the commits which are present in the "next" branch (which is the branch/commit to be released) and absent from the "release" branch (which the branch/commit already released). All Shortcut stories matching commits with a message starting with [sc-<shortcut_id>] are retrieved from Shortcut, along with the epic they belong to.

Finally, a Markdown file is generated based on the retrieved data and a template.

Per default, the helper only requires the path to the output file.

./shortcut_release_helper release_notes.md

It also supports additional options:

• --version <VERSION> is the version number of the release. This is the content of the version variable in the template.
• --name <NAME> is the name of the release. This is the content of the name variable in the template.
• --description <DESCRIPTION> is the description of the release. This is the content of the description variable in the template.
• --exclude-story-id <STORY_ID> is the ID of a story which should be ignored. Commits with this story id will be ignored. This option can be used multiple times to ignore multiple stories. Use the numeric id of the story (ie, use --exclude-story-id 130 and not --exclude-story-id sc-130 or --exclude-story-id sc130)
• --exclude-story-label <LABEL> is a story label to ignore. All commits of stories with this label will be ignored. This option can be used multiple times. Has priority over --include-story-label.
• --include-story-label <LABEL> is a story label to include. Only commits of stories with this label will be taken into account. This option can be used multiple times.
• --exclude-unparsed-commits is a flag indicating that unparsed commits should not be sent to the template (instead, an empty list will be used).

Ensure that the dependencies below (both utilities and libararies) are present in your system.

• Open API generator. This will be used to generate the Shortcut client, based on the OpenAPI definition available from the Shortcut API documentation site. The project's generator script expects an openapi-generator-cli in the PATH or in node_modules if you use npm install @openapitools/openapi-generator-cli.
• curl, to download the Shortcut OpenAPI definition.
• jq, to patch it.
• git, obviously
• rustc, at least 1.58.0

• OpenSSL

Clone the repository.

Generate the OpenAPI client via ./bin/generate_openapi_client.sh.

Build the application via cargo build

Clone the repository.

If desired Regenerate the OpenAPI client via ./bin/generate_openapi_client.sh.

Build the application via docker build . -t shortcut_release_helper:local

Build a Configuration and jinja Template file

$ shortcut_release_helper --version 3.22.1 --name "My new release" notes.md

Mount /src to a local folder to capture generated report Mount all repos to be scanned under the /src folder. Mount the config.toml and template.md.jinja under the /src folder.

Output Report will be written to the /src folder

docker run --rm -v $(pwd)/repos:/src \
    -v $(pwd)/config.toml:/src/config.toml \
    -v $(pwd)/examples/template.md.jinja:/src/template.md.jinja \
    shortcut_release_helper:local

GitHub Workflow example provided under ./examples

The software expects a config.toml configuration file in the current folder.

• The path_to_the_repo may be absolute or relative to the current directory.
• The branch_name_or_commit must be a branch name or full SHA. The short SHA will not work.

  • To pull latest commit SHA from a branch using the production tag

    git log --oneline --tags="*production*" --reverse -n 1 --format=%H

It has the following format:

# Shortcut API token, see https://help.shortcut.com/hc/en-us/articles/205701199-Shortcut-API-Tokens
api_key = "<your_api_key>"

# Template file, see below
template_file = "template.md.jinja"

# A list of one or more repository
[repositories]
repo1_name = { location = "<path_to_the_repo>", release_branch = "<branch_name_or_commit>", next_branch = "<branch_name_or_commit>" }
repo2_name = { location = "<path_to_the_repo>", release_branch = "<branch_name_or_commit>", next_branch = "<branch_name_or_commit>" }
repo3_name = { location = "<path_to_the_repo>", release_branch = "<branch_name_or_commit>", next_branch = "<branch_name_or_commit>" }

The template file is a Jinja Markdown template, which lays out the data retrieved from Shortcut.

Example provided: ./examples/template.md.jinja

The template receives the following data:

The template receives the following helpers:

The template receives the following functions:

The Markdown template uses a subset of the Jinja 2 syntax, as implemented in the minijinja crate.