This guide describes how to use the aCoRNs release notes generator to create, maintain, and publish release notes from a combination of manually written documentation and generated ticket descriptions.

1. Installing aCoRNs

Install the aCoRNs release notes generator on your system, so that you can run it locally.

Procedure

  • On Fedora, CentOS Stream, or RHEL, use the Copr repository.

    The repository is only available for actively supported releases of the operating system. If you are using a legacy, unsupported release, you can no longer install or update the package. DNF reports the following error:

    Error: This repository does not have any builds yet so you cannot enable it now.

    If this is the case, please upgrade your system.

    1. Enable the repository:

      # dnf copr enable mmuehlfeldrh/acorns

    2. Install the acorns package:

      # dnf install acorns

  • On any system that has the Docker or Podman container platform, you can use aCoRNs as a container.

    On Fedora, RHEL, and CentOS, replace docker with podman in the following commands.

    1. Download the image:

      $ docker pull quay.io/redhat-documentation/acorns
      If this image is unavailable, you can use a backup image at docker.io/msuchane/acorns:latest.

    2. Configure a command alias. Save this line in your shell configuration file:

      alias acorns="docker run -it -e BZ_API_KEY -e JIRA_API_KEY -v .:/mnt/acorns:Z redhat-documentation/acorns acorns"

      • With the Bash shell, save the line at the end of ~/.bashrc.

      • With the ZSH shell, save the line at the end of ~/.zshrc.

      • With the Fish shell, save the alias using the following command:

        $ alias --save acorns="docker run -it -e BZ_API_KEY -e JIRA_API_KEY -v .:/mnt/acorns:Z redhat-documentation/acorns acorns"

    3. Open a new terminal to reload the shell configuration.

  • On macOS, you can use the Homebrew package manager:

    This repository is currently experimental. Please report any problems with usage or installation as issues in the acorns repository.

    1. Install the Homebrew package manager as described on https://brew.sh/.

    2. Install acorns:

      $ brew install redhat-documentation/repo/acorns

  • On any system, including different Linux distributions and macOS, you can build aCoRNs from source:

    1. Install the Rust toolchain se described at https://rustup.rs/.

    2. Build and install aCoRNs from its Git repository:

      $ cargo install --git https://github.com/redhat-documentation/acorns

      If the build fails due to a missing dependency, install the missing dependency on your system and start the build again.

Verification

  • Try running acorns:

    $ acorns --version

2. Creating a new release notes project

Populate a directory with sample configuration files that aCoRNs uses to generate release notes.

Prerequisites

  • You have installed aCoRNs.

Procedure

  1. Create all configuration files that are necessary to generate release notes using aCoRNs:

    $ acorns init path-to-directory

    Replace path-to-directory with the directory where you want to store your release notes configuration.

  2. Examine the newly populated directory.

    See the README.adoc file in the directory for a description of the directory layout.

3. Enabling access to your ticket trackers

The default, sample project configuration tries to access ticket trackers that do not exist. Configure your release notes project to connect with trackers that host your tickets.

For the purpose of this document, a ticket tracker is either Bugzilla or Jira. In the future, aCoRNs might add support for additional trackers or remove support for current ones.

3.1. Configuring trackers

To enable access to your ticket trackers, enter the required settings in the trackers.yaml configuration file.

Prerequisites

  • You have installed aCoRNs.

  • You have initialized a directory with sample release notes project configuration.

Procedure

  1. In your release notes project, open the acorns/trackers.yaml file in an editor.

  2. Configure access to your Bugzilla and Jira instance.

    Currently, aCoRNs requires configuration for both trackers. If you are using only one, you can enter empty, invalid values for the other, unused trackers, such as an empty list ([]) or the default values. aCoRNs only loads the configuration for a particular tracker when your project contains tickets that come from the tracker. Otherwise, aCoRNs ignores the tracker configuration.

    • In the bugzilla entry, fill out the following, required fields for Bugzilla:

      bugzilla:
  host: "https://bugzilla.host.org" (1)
  fields:
    doc_type: (2)
      - "cf_doc_type"
    doc_text: (3)
      - "cf_release_notes"
    doc_text_status: (4)
      - "requires_doc_text"
      1 The base URL to your Bugzilla instance.
      2 The ID of the Doc Type field, which is probably a drop-down menu of values.
      3 The ID of the Doc Text field, which is a text box that contains your release note.
      4 The ID of the flag that describes the status of the release note.

    • In the jira entry, fill out the following, required fields for Jira:

      jira:
  host: "https://jira.host.org" (1)
  fields:
    doc_type: (2)
      - "customfield_12345678"
    doc_text: (3)
      - "customfield_23456789"
    doc_text_status: (4)
      - "customfield_34567890"
    docs_contact: (5)
      - "customfield_45678901"
      1 The base URL to your Jira instance.
      2 The ID of the field that lists the type of the release note. It is a drop-down menu of values.
      3 The ID of the field that contains your release note. It is a text box.
      4 The ID of the field that lists the status of the release note. It is a drop-down menu of values.
      5 The ID of the field that contains the docs contact for this release note. It is a Jira user entry.
Verification

  1. Add tickets to your release notes project.

  2. Build the release notes.

Additional resources

3.2. Finding IDs of tracker fields

To access your Bugzilla and Jira instance, you must know the internal IDs that the tracker gives to your documentation fields. The following procedure identifies the field IDs.

Prerequisites

  • You have logged into your ticket tracker.

Procedure

  1. Open a ticket that has your documentation fields.

  2. In Bugzilla, click Show advanced fields if you cannot see your documentation fields.

  3. Right-click the name of a documentation field, such as the Doc Type or Release note text field.

  4. In the right-click menu, select Inspect.

  5. Your web browser displays a toolbar that lists the elements of the web page, and highlights the element that represents the selected documentation field.

  6. Find the field ID in the label tag:

    • With Bugzilla:

      <label for="cf_release_notes">

    • With Jira:

      <label for="customfield_12345678">

3.3. Required and optional fields in tracker configuration

The lists below describe mandatory and optional fields for the acorns/trackers.yaml configuration file.

Bugzilla configuration
bugzilla:
  host: "https://bugzilla.host.org"
  fields:
    # Required
    doc_type:
      - "cf_doc_type"
    doc_text:
      - "cf_release_notes"
    doc_text_status:
      - "requires_doc_text"
    # Optional
    docs_contact:
      - "cf_my_docs_contact"
    target_release:
      - "cf_internal_target_release"
    subsystems:
      - "pool"

The following fields are required:

host

The base URL to your Bugzilla instance.

doc_type

The ID of the Doc Type field, which is probably a drop-down menu of values.

doc_text

The ID of the Doc Text field, which is a text box that contains your release note.

doc_text_status

The ID of the flag that describes the status of the release note.

The following fields are optional:

docs_contact

By default, aCoRNs uses the standard Bugzilla Docs Contact field. You can override it with a custom field.

target_release

By default, aCoRNs uses the standard Bugzilla Target Release field. You can override it with a custom field.

subsystems

This field is required only if you configure your templates to organize using the subsystem.

Currently, this field expects an Agile Pool menu.

Jira configuration
jira:
  host: "https://jira.host.org"
  private_projects:
    - "SECRETPROJECT"
    - "MYPROJECT"
  fields:
    # Required
    doc_type:
      - "customfield_12345678"
    doc_text:
      - "customfield_23456789"
    doc_text_status:
      - "customfield_34567890"
    docs_contact:
      - "customfield_45678901"
    # Optional
    target_release:
      - "customfield_56789012"
    subsystems:
      - "customfield_67890123"

The following fields are required:

host

The base URL to your Jira instance.

doc_type

The ID of the field that lists the type of the release note. It is a drop-down menu of values.

doc_text

The ID of the field that contains your release note. It is a text box.

doc_text_status

The ID of the field that lists the status of the release note. It is a drop-down menu of values.

The following fields are optional:

private_projects

If you set certain Jira projects as private, all ticket IDs in these projects will be non-clickable, even if the ticket itself is public in Jira.

target_release

By default, aCoRNs uses the standard Jira Fix Version/s field. You can override it with a custom field.

subsystems

This field is required only if you configure your templates to organize using the subsystem. It is a drop-down menu of values.

Multiple field IDs from different projects

Settings in the fields entry always accept a list of IDs that aCoRNs tries out successively.

For example, if you use Jira tickets from three different projects that each set a different doc text field, you can list all field IDs:

jira:
  host: "https://jira.host.org"
  fields:
    # All possible IDs
    doc_text:
      - "customfield_23456789"
      - "customfield_34567890"
      - "customfield_45678901"

3.4. Obtaining API keys to ticket trackers

To log into your ticket trackers, aCoRNs needs your API keys. If you do not have or do not know any API keys, you can generate them.

Prerequisites

  • You have logged into your Jira and Bugzilla accounts.

  • Your Jira instance enables the Personal Access Tokens plug-in (com.atlassian.pats).

Procedure

  1. Generate a Jira API key:

    1. Click your profile picture in the upper-right corner and select Profile.

    2. Go to the Personal Access Tokens tab.

    3. Click Create token.

    4. In the Token Name field, enter a name for your new API key.

    5. Under Expiry date, set for how long this API key stays valid.

    6. Click Create.

    7. Note down the API key displayed at the top of the page.

  2. Generate a Bugzilla API key:

    1. Click your name in the upper-right corner and select Preferences.

    2. Click API Keys.

    3. Under the New API key heading, check the checkbox and enter a name for your new API key.

    4. Click Submit Changes.

    5. Note down the API key displayed at the top of the page.

  3. Save your API keys in a password manager.

    You cannot recover the API keys from Jira or Bugzilla. You can only generate new ones and revoke existing ones.

4. Adding tickets to your project

The default, sample project configuration lists tickets that do not exist. Populate your release notes with existing tickets that contain documentation.

4.1. Specifying tickets

To add tickets to your project, specify them in the tickets.yaml configuration file.

Prerequisites

  • You have installed aCoRNs.

  • You have initialized a directory with sample release notes project configuration.

  • You have configured tracker access.

Procedure

  1. In your release notes project, open the acorns/tickets.yaml file in an editor.

  2. Remove or comment out the sample configuration, which points to non-existent tickets.

  3. Add several tickets that contain release note documentation in the following format.

    To test a new release notes project, it is recommended to add tickets that cover all possible doc types.

    • Bugzilla tickets are identified by their ID number:

      - [BZ, key: 1234567]
- [BZ, key: 2345678]

    • Jira tickets are identified by their key, which consists of the project name and a number:

      - [Jira, key: PROJECTA-123456]
- [Jira, key: PROJECTB-234567]
Additional resources

4.2. Alternative methods to specify tickets

The acorns/tickets.yaml configuration file recognizes several kinds of syntax to identify tickets that belong into your release notes document.

The general structure of a ticket entry

Each entry in the acorns/tickets.yaml configuration file follows this structure:

  1. The - character to start a list item.

  2. A pair of square brackets ([ ]) to contain the entry.

  3. A keyword that identifies the ticket tracker, followed by a comma. The following values are supported:

    • Jira

    • Bugzilla

    • BZ as a shorthand for Bugzilla

  4. A keyword that specifies the method to retrieve tickets. The following values are supported:

    • key to select a single ticket, followed by the ID or key of the ticket.

    • search to select all tickets that match a search, followed by a string in the format that the ticket tracker recognizes as a search query.

  5. Optional: The overrides keyword, which enables you to manually override the value of the ticket’s doc type, components, or subsystems.

  6. Optional: The references keyword, which enables you to attach multiple additional ticket IDs to this release note.

Example 1. Tickets listed individually, using their IDs or keys
Jira tickets
- [Jira, key: PROJECTA-123456]
- [Jira, key: PROJECTB-234567]
- [Jira, key: PROJECTC-345678]
Bugzilla tickets
- [BZ, key: 1234567]
- [BZ, key: 2345678]
Example 2. Queries that result in multiple tickets
A Bugzilla query copied from the URL of a Bugzilla search
- [BZ, search: 'bug_status=VERIFIED&bug_status=CLOSED&product=Our Container Platform&target_release=1.23.0']
All Bugzilla bugs that block a particular bug, sometimes called a tracker
- [BZ, search: '"f1=blocked&o1=equals&v1=12345678"']
A standard JQL query
- [Jira, search: 'project="CentOS Stream" AND priority=Blocker']
A saved Jira issue filter identified using JQL
- [Jira, search: 'filter = 12345678']
All Jira tickets that are attached to an epic as its children
- [Jira, search: 'issue in childIssuesOf("PROJECT-123456")']
All Jira tickets that are linked from a particular ticket, such as blocking or duplicating it
- [Jira, search: 'issue in linkedIssues("PROJECT-123456")']
Example 3. Overrides
Overriding the subsystem value of a ticket
- [BZ, key: 1234567, { overrides: {subsystems: [sst_different]} }]
Overriding the doc type value of a whole search
- [Jira, search: 'project="CentOS Stream" AND priority=Blocker', { overrides: {doc_type: "Known Issue"} }]
Example 4. References
- [BZ, key: 1234567, { references: [[BZ, key: 2345678], [Jira, key: PROJECTC-345678]] }]
Additional resources

5. Building release notes

Build a release notes project in a local directory that contains your aCoRNs configuration files.

Prerequisites

  • You have installed aCoRNs.

  • You have configured access to your tickets trackers.

  • You have added tickets to your release notes project configuration.

Procedure

  1. Navigate to your release notes project:

    $ cd my-release-notes

  2. Set your API keys for Bugzilla and Jira:

    $ export BZ_API_KEY=my-bugzilla-key

$ export JIRA_API_KEY=my-jira-key

    If you are using a shell that is not compatible with the Bourne shell syntax, adjust the commands.

    For example, with the Fish shell:

    $ set -x BZ_API_KEY=my-bugzilla-key

$ set -x JIRA_API_KEY my-jira-key

  3. Generate release notes:

    $ acorns build

  4. Compile the external and internal version of the AsciiDoc document:

    $ asciidoctor --safe -vn main-external.adoc

$ asciidoctor --safe -vn main-internal.adoc

  5. Open the main-external.html and main-internal.html files in a web browser to preview the document.

    In the GNOME desktop environment, you can use the following commands:

    $ gio open main-external.html

$ gio open main-internal.html

6. Organizing tickets in your project using templates

The default, sample project configuration organizes your release notes based on their doc type. You can configure the templates in your release notes project to organize release notes using other criteria, and edit the content of the generated files.

6.1. Structuring templates

To structure your templates, edit the settings in the templates.yaml configuration file.

Prerequisites

  • You have installed aCoRNs.

  • You have configured access to your tickets trackers.

  • You have added tickets to your release notes project configuration.

Procedure

  1. In your release notes project, open the acorns/templates.yaml file in an editor.

  2. Edit the templates to organize your release notes in the rendered document:

    • In a relatively small project with few release notes, you might want to continue organizing just by one property of release notes, such as just by doc type, just by component, or just by subsystem.

      In this case, keep the chapters entry of the configuration file and edit the rules in it.

    • In a relatively large project with many release notes, you might want to further divide your release notes by several properties, which results in several levels of nested sections. For example, you can organize by doc type at the base level and further divide each doc type chapter into subsections based on components.

      In this case:

      1. Add the subsections entry at the top of the configuration file, where you define the deeper levels of nested organization. This entry is described in Available options to organize release notes.

      2. Edit the rules in the chapters entry of the configuration file. Include the organizing rules that you defined in the subsections entry. Use the YaML anchors syntax to include previously defined rules.

  3. Rebuild your release notes and examine the generated files in the acorns/generated/internal/ directory.

  4. Include the generated files in your main-template.adoc file.

Verification

  1. Build an HTML preview of the internal document:

    # asciidoctor --safe -vn internal.adoc

  2. Open the preview and check the document structure.

Additional resources

6.2. Available options to organize release notes

The acorns/templates.yaml configuration file recognizes several options and properties to organize release notes in your document.

The base level of organization

The configuration file always requires the chapters entry, which defines the initial, base organization level.

This level is called chapters because it usually generates files that you include directly from your main-template.adoc file. These generated files can either be reference modules or assemblies, depending on their content.

The chapters entry has the following syntax:

chapters:

  - title: "Bug fixes" (1)
    filter: (2)
      doc_type: (3)
        - "Bug Fix" (4)

  - title: "New features"
    intro_abstract: "This part describes new features and major enhancements introduced in {Product}." (5)
    filter:
      doc_type:
        - "Enhancement"
        - "Feature" (6)
    subsections: (7)
      - *installer
      - *networking
      - *storage
      - *virtualization
1 The title (heading) of the generated AsciiDoc file.
2 Settings that define which tickets appear in this chapter or subsection.
3 The filter settings accept the following properties to select tickets:

  • doc_type

  • component

  • subsystem
4 This chapter lists all tickets that have the Bug Fix doc type.
5 Optional: An abstract (introduction) of this chapter. The text appears directly under the title and can contain arbitrary AsciiDoc syntax, including attributes.
6 Optional: This chapter lists all tickets that have either the Enhancement or Feature doc type. You can group multiple values together and they do not have to be related.
7 Optional: To enable a deeper level of nesting, this chapter includes subsections with different organizing settings. This chapter starts with tickets of the Enhancement and Feature doc types, and divides them further by rules defined in the listed subsections.

The asterisk (*) at the start of each subsection name is the YaML anchor syntax that refers to elements written elsewhere in the configuration file, labeled with this anchor.

Subsections can also be called sections in the configuration file for legacy compatibility.
Deeper levels of organization

If you enable deeper levels of organization by specifying the subsections (or sections) option in chapters, you must add the subsections (or sections) entry at the top of the templates.yaml file.

The subsections entry defines rules organizing at levels that you do not include yourself in the main-template.adoc file, but rather, the base-level chapters include these generated files.

The subsections entry has the following syntax, which is identical to the chapters syntax, except for the addition of YaML anchors:

subsections:

  - &networking (1)
    title: "Networking" (2)
    filter: (3)
      subsystem:
        - 'sst_networking' (4)

  - &installer
    title: "Installer and image creation"
    intro_abstract: "Installing {Product} on physical and virtual systems."
    filter:
      subsystem:
        - 'ssg_front_door'
        - 'sst_front_door'
        - 'sst_installer'
        - 'sst_image_builder'
        - 'sst_composer' (5)
1 The ampersand (&) character is the YaML anchor syntax that names this section, so that you can later reuse it elsewhere in the configuration file by referring to this name.
2 The title (heading) of the generated AsciiDoc file.
3 A filter that further limits the tickets that come from the parent chapter.
4 This section only lists tickets within the chapter that belong to the sst_networking subsystem.
5 This section only lists tickets within the chapter that belong to any of the listed subsystems.
Example 5. Release notes organized by doc type
chapters:
  - title: "New features"
    intro_abstract: "This part describes new features and major enhancements introduced in {Product}."
    filter:
      doc_type:
        - "Enhancement"
        - "Release Note"
        - "Feature"
  - title: "Bug fixes"
    intro_abstract: "This part describes bugs fixed in {Product} that have a significant impact on users."
    filter:
      doc_type:
        - "Bug Fix"
  - title: "Technology Previews"
    intro_abstract: |
      This part provides a list of all Technology Previews available in {Product}.

      For information on the scope of support for Technology Preview features, see link:https://example.org/[Example]. (1)
    filter:
      doc_type:
        - "Technology Preview"
  - title: "Deprecated functionality"
    intro_abstract: |
       This part provides an overview of functionality that has been _deprecated_ in {Product}.

       Deprecated functionality will likely not be supported in future major releases of this product and is not recommended for new deployments.
    filter:
      doc_type:
        - "Deprecated Functionality"
  - title: "Known issues"
    intro_abstract: "This part describes known issues in {Product}."
    filter:
      doc_type:
        - "Known Issue"
1 The introduction can span several paragraphs. Use the | YaML syntax to start a multiline string, with blank lines to separate paragraphs.
Example 6. Release notes organized by doc type and component
subsections:
  - &web_console
    title: "Web console"
    filter:
      component:
        - "Management Console"
  - &oc
    title: "OpenShift CLI (oc)"
    filter:
      component:
        - "oc"
  - &images
    title: "Images"
    filter:
      component:
        - "Image Registry"
  - &olm
    title: "Operator"
    filter:
      component:
        - "OLM"
        - "Operator SDK"

chapters:
  - title: "New features"
    intro_abstract: "This part describes new features and major enhancements introduced in {Product}."
    filter:
      doc_type:
        - "Enhancement"
        - "Release Note"
        - "Feature"
    subsections: (1)
      - *web_console
      - *oc
      - *images
      - *olm
  - title: "Bug fixes"
    intro_abstract: "This part describes bugs fixed in {Product} that have a significant impact on users."
    filter:
      doc_type:
        - "Bug Fix"
    subsections:
      - *web_console
      - *oc
      - *images
      - *olm
  - title: "Technology Previews"
    intro_abstract: |
      This part provides a list of all Technology Previews available in {Product}.

      For information on the scope of support for Technology Preview features, see link:https://example.org/[Example].
    filter:
      doc_type:
        - "Technology Preview"
    subsections:
      - *web_console
      - *oc
      - *images
      - *olm
  - title: "Deprecated functionality"
    intro_abstract: |
       This part provides an overview of functionality that has been _deprecated_ in {Product}.

       Deprecated functionality will likely not be supported in future major releases of this product and is not recommended for new deployments.
    filter:
      doc_type:
        - "Deprecated Functionality"
    subsections:
      - *web_console
      - *oc
      - *images
      - *olm
  - title: "Known issues" (2)
    intro_abstract: "This part describes known issues in {Product}."
    filter:
      doc_type:
        - "Known Issue"
1 You must repeat the subsections list in each chapter configuration that you want to subdivide into deeper organizing levels.
2 This chapter does not list any subsections. As a result, all tickets in this chapter will appear together in the same chapter, with no further division into subsections.

6.3. Organizing a ticket manually

aCoRNs organizes your release notes based on the ticket properties as defined in templates.yaml. If a release note appears in the wrong section, but you cannot edit the ticket itself, you can override certain ticket properties in the tickets.yaml file.

Prerequisites

  • You have added tickets to your release notes project configuration.

  • You have defined release note templates.

Procedure

  1. Find the line that defines the ticket in tickets.yaml.

    Example 7. A ticket without overrides
    - [Jira, key: PROJECT-1234]

  2. Add an override to adjust the release note organization:

    Example 8. A ticket with an override
    - [Jira, key: PROJECT-1234, { overrides: {components: [CustomComponent]} }]

    In the overrides block, you can use the following elements to override selected ticket properties:

    components: [Component1, Component2]

    Set custom components for this ticket.

    doc_type: Type

    Set a custom doc type for this ticket.

    subsystems: [SST1, SST2]

    Set custom subsystems for this ticket.

Verification

  1. Build an HTML preview of the internal document:

    # asciidoctor --safe -vn internal.adoc

  2. Open the preview and check where the release note appears.

6.4. Referring to another ticket from a release note

Every release note ends with a reference to the ticket that it comes from. You can extend this reference to also include other, related tickets. In the release note body, you can also refer to other release notes within the document.

Prerequisites

  • You have added tickets to your release notes project configuration.

Procedure

  • To refer to additional tickets at the end of the release note:

    1. Find the line that defines the ticket in tickets.yaml.

      Example 9. A ticket without references
      - [Jira, key: PROJECT-1234]

    2. Add references to other tickets.

      Example 10. A ticket with references
      - [Jira, key: PROJECT-1234, { references: [[BZ, key: 123456], [Jira, key: PROJECT-2345]] }]

      The references block is a list that specifies tickets using the same syntax as the main list in tickets.yaml.

  • To refer to another release note within the document, use the standard AsciiDoc xref syntax in the release note body.

    You can refer to any release note using an ID that corresponds to its ticket tracker and ticket key, separated by a dash. For example:

    Example 11. References to release notes
    See xref:BZ-123456[] and xref:Jira-PROJECT-1234[].

6.5. Documentation files generated from templates

Every chapter and section defined in the templates.yaml file attempts to generate a matching AsciiDoc file. The generated file can either be a reference module or an assembly, depending on its content. The following rules decide the type and name of the generated file:

  • If this chapter or section includes no other subsections definitions, it generates a reference module. The file name of the module is:

    ref_lowercase-title-with-certain-replacements.adoc

  • If this chapter or section does include additional subsections definitions, it generates an assembly file, which then includes other modules or assemblies in the same directory. The file name of the assembly is:

    assembly_lowercase-title-with-certain-replacements.adoc

  • If a section is included from another chapter or a section, its file name lists the complete include path:

    ref_title-of-section-title-of-its-including-parent.adoc

  • If no tickets in your project match the filter rules defined in this chapter or section, it does not generate any file.

    Top-level chapters are an exception to this rule. These chapters are generated even if they are empty of release notes, and in that case, they end up being completely empty files. This is a feature that ensures that include directives do not break in your main AsciiDoc file.

    For example:

    • A Known issues chapter uses a filter that looks for tickets with the Known Issue doc type. However, none of your tickets in this project is a Known Issue. As a result, the assembly_known-issues.adoc file is generated as empty.

    • A chapter includes subsections that look for three specific components. However, none of your tickets belong to these components. As a result, the section modules are not generated, and the chapter assembly file is generated empty.

    • A chapter matches several tickets, the doc text status of all the tickets is incomplete. As a result, the file is generated for the internal version of the document with the release note content, but in the external version, it is an empty file.

7. Adding an explanatory footnote to private tickets

Public ticket IDs contain a clickable link to the ticket. Private ticket IDs are non-clickable. If this is confusing to the readers, you can automatically generate a footnote next to private ticket IDs that explains why the ticket link is missing.

Procedure

  1. Prepare the text that you want to add to every private ticket ID as a footnote. For example:

    This ticket is private.

  2. In your release notes project, enter a footnote with the PrivateTicketFootnote ID in a manually written AsciiDoc file.

    The footnote must appear before you include the first file generated by aCoRNs, such as near the book introduction or at the start of the main file. This requirement is caused by a technical limitation in the deprecated footnoteref macro.

    You can store the footnote text in a separate attribute, so that it is more convenient to edit:

    Example 12. Placement of the footnote in main-template.adoc
    :private-footnote-text: This ticket is private.

= Release notes for {Product} {Version}

This is the abstract paragraph.

Release notes include links to access the original tracking tickets. Private tickets have no links and instead feature the following footnote{blank}footnoteref:[PrivateTicketFootnote,{private-footnote-text}].

<Include your modules here.>
Verification

  1. Build the release notes project.

  2. Open a preview.

  3. Compare the IDs of public and private tickets. Verify that all private tickets feature the footnote.

    For example:

Additional resources

8. Publishing previous releases in one continuous document

As a release notes maintainer, you can publish several releases or all release history in one document. Only the latest release is actively generated by acorns, while the previous releases are archived as manual content. You can see an example of a similar setup in the RHEL 8.2 release notes.

Prerequisites

  • You have a working acorns configuration in a Git repository, later called the source repository.

  • A CI/CD pipeline runs acorns and saves the generated content in a separate, generated repository.

    If you do not use this workflow, you can still archive previous releases in one document, but the procedure is slightly different.

Procedure

  1. Generate your release notes for the current release as usual.

  2. When the current release is published and done, you can archive it.

  3. Open your generated RN repository.

  4. Navigate to the external branch of the current release.

  5. Download the latest generated files.

  6. In your source directory, create a new directory under the manual-content/ directory. Name it such that it refers to the release that you are archiving: for example, manual-content/RHOSO-18.0-Beta/.

  7. Move all the downloaded generated files into the newly created directory in your source repository.

  8. In the same directory, create a main.adoc assembly. Set a title that refers to the archived version, such as RHOSO 18.0 Beta.

  9. In the assembly, include all the downloaded generated files.

    Because you are including files in the same directory, specify only the file names with no directory path in the include directives.

  10. Include the new assembly from your master file, such as the master_template.adoc file. For example:

    include::manual-content/RHOSO-18.0-Beta/main.adoc[leveloffset=+1]

  11. You now have a RHOSO 18.0 Beta chapter in your RN document that includes all release notes for that specific release, saved as static, manual content that originated from the generated repository.

  12. As acorns regenerates new release notes, they work towards the following release. In your master file, they are included from the acorns/generated/ directory, until you want to archive this release as a another static assembly.

  13. Optional: If you want your current, actively generated release to also appear in a separate chapter of the document:

    1. Create a new assembly with a title appropriate to the current release.

    2. Move the include directives that refer to acorns/generated/ from your master file to the new assembly.

    3. Include the new assembly in your master file.

9. Differences between aCoRNs and CoRN 3

aCoRNs is a successor to the previous CoRN release notes generator, version 3. If you are migrating from CoRN 3 to aCoRNs, compare the different format of the configuration files and generated files:

CoRN 3 files aCoRNs files

corn.yaml

acorns/tickets.yaml

corn-template/

acorns/templates.yaml

corn-generated-external/

acorns/generated/external/

corn-generated-internal/

acorns/generated/internal/

corn-generated-internal/status-table.html

acorns/generated/status-table.html

10. Known issues and limitations

See the issues in the aCoRNs repository: https://github.com/redhat-documentation/acorns/issues.

1. This ticket is private.