Couchbase Release Notes Builder

Introduction

Creating release notes from Jira issues is pretty dull, AmIRight?

Each module’s release note is in a different format, and you need a different Jira search to find the ones that go in the notes (and don’t forget to filter out the private ones).

Figure 1. cb_release_notes is off and running!

Well, the boffins in the docs team have put together a small Python script to take some of the tedium out building release notes.

Warning

This isn’t going to do the whole thing automatically, but we’re aiming to cover the dull bits of the process. After generating the release notes, make sure you look through them to make sure they are correct!

Installation

The script and its associated libraries are packaged as single executable.

1. Download package.zip from https://github.com/RayOffiah/cb-release-notes/releases and unpack it into a spare directory.

2. Your directory set up should look something like this:

   📂
     📄 cb_release_notes              (1)
     📄 cb_release_notes_config.yml   (2)
     📂 templates
       📄 couchbase-mobile.jinja2     (3)
       📄 couchbase-docs-server.jinja2

   1. The application

   2. The application’s configuration file.

   3. A template for generating the AsciiDoc release note.

      Note	The location of the templates can be specified in cb_release_notes_config.yaml.

Configuration

Release notes are created from a release set specified in the configuration file:

# Configuration file for the release notes builder
version: "1.0" # (1)

password_file: ./.passwords.yaml #(2)
templates_directory: ./templates #(3)
jira_batch_size: 50

release_settings: #(4)

  - name: couchbase-mobile
    url: https://jira.issues.couchbase.com #(5)
    jql: project = CBL AND issuetype in (Bug, Improvement) # (6)
      AND Component in (.NET, C, IOS, Java, Java-Android, Kotlin, Kotlin-Android, LiteCore)
      AND (fixVersion = {{release_number}} OR labels IN (known_issue))
      ORDER BY key ASC
    fields:
      - name: module
        type: select
        message: 'Select module:'
        choices:
          - Android
          - C
          - .NET
          - Java
          - Javascript
          - Objective-C
          - Swift
      - name: release_number
        type: text
        message: 'Enter the release number:'
      - name: release_date
        type: text
        message: 'Enter the release date (month year)'
    template: couchbase-mobile.jinja2

  - name: docs-server
    url: https://jira.issues.couchbase.com
    jql: project = "Couchbase Server" AND fixVersion = {{release_number}}
         AND (labels = releasenote OR summary ~ BP)
         AND level is EMPTY AND summary !~ "System Test" AND resolution not in (Declined, "Won't Fix")
         AND component in (analytics, eventing, fts, ns_server, query, query_tools,
         rbac, XDCR, memcached, secondary-index, installer,
         storage-engine, view-engine, couchbase-bucket)
         ORDER BY key ASC
    fields:
      - name: release_date
        type: text
        message: 'Enter the release date (Month Year):'
      - name: release_number
        type: text
        message: 'Enter the release number:'
    template: couchbase-docs-server.jinja2

  - name: sync-gateway
    url: https://jira.issues.couchbase.com
    jql: project = CBG AND issuetype in (Bug, "New Feature", Epic, Improvement)
      AND (fixVersion = {{release_number}} OR labels IN (known_issue))
      AND level = "Public" # (7)
      ORDER BY key ASC
    fields: #(8)
      - name: release_number
        type: text
        message: 'Enter the release number:'
      - name: release_date
        type: text
        message: 'Enter the release date (Month Year):'
    template: sync-gateway.jinja2

1. The version of the application. This is just to help keep track of things.

2. The location of the passwords file. URLS in the release-settings require a username/password or a token for access. These are stored in a separate file keyed to the URL:

   https://issues.couchbase.com:
     username: fred.smith
     password: fancypants120
   
   https://atlassian.couchbase.com:
     token: HUFGHitha354HHFHAPLKHJ

3. The location of the Jinja2 templates used to render the release notes.

4. Marks the beginning of a release set. When the program runs, you will be presented with a list of release sets (see Figure 1) to pick from.

5. The URL for the issue database.

   Important

   The URL is used as the key for the password file.Make sure that the entries match up exactly.

6. The JQL statement used to retrieve the Jiras making up the release note. You can use macros variables ({{variable_name}}) inside the JQL, which will need to be filled in when the generator runs.

   Tip	Every release set should, at the very least, require the user to enter a release number. (However, we’ve chosen not to make this compulsory.)

7. A lot of Jiras are not meant for public consumption, so it’s a good idea to check that the Jiras included in the release note are marked for public consumption.

8. The 'fields' section is a list of fields that the program will ask for. The user will fill in the entries, and the value will be stored under the given name (release_number for example). The fields can be referenced in the jql statement and/or the jinja template. The program supports five field types:

   text	An arbitrary field of text.
   multiline	The same as text, except you can enter multiple lines.
   editor	This will open your system editor for editing large wodges of text. Warning This one is experimental; we recommend you don’t use it in production.
   select	A menu selection from which the user can select a single value.
   choice	A multiple choice selection. Figure 2. Making a multiple selection

9. The template that will be used to render the release note.

   For more information on Jinja2 templates, see the Jinja Documentation

Running the program

The program is a Python script packaged as an executable (hence the size!) Run it from the shell:

./cb_release_note

And follow the instructions.

Now copy the generated file to the partials directory of the module under release. Then include:: the file at the top of the existing release note.

Developing and Building

You will need a Python environment. The following should be a minimal way to build the script.

brew install pyenv  # will install the whole world

pyenv init
# NOW copy/paste the suggested code into your .zshrc, and restart your shell session

# replace with the current stable Python version number from https://www.python.org/downloads/
pyenv install 3.13.3

pyenv shell 3.13.3  # this points Python to the installed version just for THIS shell session

pip install -r requirements.txt

./packager.sh
# creates package/ and zips it up into package.zip

./package/cb-release-note

TODO: document how to create a new Release on Github.