Skip to content

rich-jira-release-notes 📄🤖

Made with Terminalizer

Introduction

As of today Jira is not able to export auto-generated release notes with assets such as images (see: Atlassion Support - Create release notes).

The CLI provided by this repository is able to do so and serves as a workaround until Atlassian provides this functionality out-of-the-box.

Installation

  1. Install Python 3.12

  2. Create a virtual environment:

    python3.12 -m venv ./.venv

  3. Activate the virtual environment:

    ./.venv/scripts/activate

  4. Install the CLI:

    pip install git+https://github.com/TrisNol/rich-jira-release-notes.git@develop

  5. Check that the CLI is available:

    rich-jira-release-notes version

Usage

  1. Create an .env file of the following structure

    JIRA_URL=<your_domain>.atlassian.net
JIRA_USER=<mail of the service/human user providing the token>
JIRA_TOKEN=<PAT>

    Alternatively, you can provide those values as regular env. variables

  2. Create a Jinja template in your project (Example). You will have access to a variable called issues representing a list of objects of type JiraIssue: python class JiraIssue(BaseModel): id: str # Jira internal ticket ID key: str # Ticket number (<project>-<number>) type: str # one of: ["Bug", "Story", "Task", "Epic", "Sub-task"] fields: dict[str, JiraField] # Ticket fields retrieved A JiraField exposes an attribute value of different datatypes depending on the type of field selected:

    • JiraFieldType.TEXT: Contains raw text
    • JiraFieldType.RICH_TEXT: Contains rich text in Markdown format
    • JiraFieldType.CHECKBOX: Contains a list of strings representing the ticked checkboxes of the field

  3. Construct a JQL query fitting your use case; example:

    project = <Jira_Project_Key> AND fixVersion = "<Release_Version>"

    Replace placeholders like so:

    project = DEV and fixVersion = "4.2.0"

  4. Determine the fields to export; example:

    Summary, Release Notes

  5. Run sh rich-jira-release-notes generate 'YOUR_JQL_QUERY' fields="YOUR_FIELDS"

    Example:

    rich-jira-release-notes generate 'project = DEV and fixVersion = "0.0.0"' "Summary, Release Notes, Checkboxes"

  6. Retrieve release notes from the dist/ directory

CLI reference

$ rich-jira-release-notes [OPTIONS] COMMAND [ARGS]...

Options:

  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • version
  • generate: Generate release notes

rich-jira-release-notes version

Usage:

$ rich-jira-release-notes version [OPTIONS]

Options:

  • --help: Show this message and exit.

rich-jira-release-notes generate

Generate release notes

Usage:

$ rich-jira-release-notes generate [OPTIONS] JQL_QUERY [FIELDS]

Arguments:

  • JQL_QUERY: JQL query to search for issues [required]
  • [FIELDS]: Comma separated list of fields to include in the release notes [default: Summary, Release Notes]

Options:

  • --convert-to-markdown / --no-convert-to-markdown: Convert HTML to Markdown [default: convert-to-markdown]
  • --output-dir TEXT: Output directory [default: dist]
  • --template-file TEXT: Template file to use [default: ./template.md.jinja]
  • --config-file TEXT: Path to JSON configuration file
  • --help: Show this message and exit.