❤
npm
Sign UpSign In

release-documentation-cli

5.2.4 • Public • Published

Release Documentation CLI

Overview

The Release Documentation CLI tool aims to make Github release documentation easier. It will generate a Github release automatically, containing artifacts and a changelog based on the changes made since the last tagged release.

Note: It is worth noting that this tool uses the generate-changelog library. Enforce conventional commit types in your project commit messages in order for the changelog to be generated. For example "test: added unit tests"

For Breaking changes or major versions use the following format

feat: Author Api v2

BREAKING CHANGE:  client request has changed

Requirements for complete release compliance

In order to move away from release request forms and google sheets, and to have fully automated releases in compliance with NewsUK's standards, there are several features of this tool that are required.

Changelog requirements

Releases should include a changelog with the following inofrmation:

  • Test Evidence
  • Build Link
  • Rollback Link

The test evidence should contain all of the relevant testing for the release including links to the specific builds on their respective CI platforms. The build link should link to the CI job that has run the latest build to be deployed, with the changes applied included. The rollback link should provide a link to CI job that can revert the release to the previous version.

Each of these can be configured in the config file as detailed below.

ServiceNow

When a release is being booked a change request needs to be made in ServiceNow (NewsUKs chosen change and release management service). This can be done with the create-chage-request command, or using the --bookRelease option in the new command (this will also book the release into the release spreadsheet).

You will need to assume a role that has access to the credentials for this sheet.

A ServiceNow Application Service id(s) needs to be provided in the config file. This is unique to your project and can be requested from the release manager. Relevant environment variables must be set up as described below to use this feature.

New Relic

There is a functionality in New Relic where you can mark deployments for better visibility of changes. In order to pin point such events release-documentation-cli can be invoked with the new-relic-deployment command with the parameters --appName, denoting the application name in New Relic where the deployment marker should be put, and --apiKey, holding the authentication key for New Relic.

Example:

release new-relic-deployment --appName ACS:Auth:prod --apiKey NRAK-xxxxxxxxxxxxx

Application name within New Relic can be configured with the following setting in release-documentation-cli.config.json file:

"releaseDetails" : {
    "newRelicAppName": "ACS:Auth:prod"
}

IMPORTANT: When invoked with this command, the release tool will go the invoking github repository, search for the latest release, get its tag and use it for metadata for the New Relic deployment event. For the New Relic deployments to be accurate, make sure you invoke release new-relic-deployment as close to the actual app deployment time as possible, because it generates its own timestamp.

Github PR template

A github template must be in place for all PRs on the project. This is so that the changes listed in the releases change log and be followed back and are well documented.

Example workflows

Example 1

To create a new pre-release on github using the supplied release doc config, book it into a google sheet, create a change request in ServiceNow and mark it approved by the product owner, a job can be run like this:

release bump-version
git push --tags
release new --productOwner "Product Owner" --scheduled --skipReleaseNotes --bookRelease

Once the pre-release has been deployed, it can be promoted to a release using the promote command:

release promote

Example 2

An example work flow of the release process that uses emails and seperated product owner sign-off:

release bump-version
git push --tags
release new --scheduled --skipReleaseNotes --awaitingApproval
VERSION=$(release latest-pre-release -r)
release email --type po-approval --versionTag ${VERSION} --emailUser joe.bloggs@email.com --emailPass pa55word --emailRecipients product.owner@email.com

An email would then be sent to the product owner that looks like this:

Hi,


    The release for version <VERSION> of <PROJECT> on <PLATFORM> can be found here:

    <LINK TO THE GITHUB RELEASE DOCS>

    You can approve by clicking this link

    <LINK TO THE RELEASE BOOKING JOB>

    and running the job.

    Thanks

The Product owner would then review the release docs and once satisfied could run the job in the second link that would contain these commands to book and approve the release:

VERSION=$(release latest-pre-release -r)
release book --productOwner "Product Owner" --versionTag ${VERSION}
release create-change-request --scheduled --updateGitRelease
release approve --productOwner "Product Owner"

Again, on completion fo the release deployment, the git pre-release can be promoted to a release with

release promote

Example release

example_release

Setup

Export the following variables in your shell of choice:

GIT_USERNAME GIT_ACCESS_TOKEN

Export the following depending on which CI platform you are using:

BITRISE_TOKEN JENKINS_TOKEN BUDDYBUILD_TOKEN TEAMCITY_TOKEN CIRCLE_TOKEN

You may override the default TeamCity URL by setting:

TEAMCITY_URL

You can also define the default branch (e.g. main) used for creating releases by setting:

DEFAULT_BRANCH

Configuring the release-documentation-cli.config

The Release Documentation CLI aims to integrate with a variety of projects. Depending on the setup of the project additional configuration options may need to be provided.

The configuration file must be placed next to the package.json file within the project structure. release-documentation-cli.config.json

The following configuration options are available:

gitConfigPath

If your package.json file is not at the root of the project then you will need to specify the following option allowing the release-documentation-cli to read the git configuration of the project:

{
  "gitConfigPath": "../.git/config",
}

releaseInstructionsPath

If your project has specific instructions on how to release, add them to a markdown file in your project and put the path to the file as the value for this key:

{
  "releaseInstructionsPath": "./path/to/release-instructions.md",
}

testEvidenceJobs

If your release needs to gather test evidence, add the build jobs running the tests to the config file. Artifact names should also be added as an array. (At the moment artifacts can only be added for jobs that use the Jenkins CI tool).

If you are using Circle, you will need to add a flag to your config: useBuildName: true to ensure that the tool gets the right build out of the API.

See the example below:

{
"testEvidenceJobs":[
        {
            "buildName": "ci-tests",
            "ciTool": "jenkins",
            "artifacts": ["testcoverage.html"],
            "branch": "dev"
        },
        {
            "buildName": "even-more-ci-tests",
            "ciTool": "teamcity",
            "branch": "master"
        },
        {
            "buildName": "even-more-ci-tests",
            "ciTool": "circle",
            "branch": "master",
            "useBuildName": true
        }
    ]
}

builds

If your release needs the latest build, add the build job to the config.

See the example below:

{
"builds":[
        {
            "buildName": "release-documentation-cli",
            "ciTool": "teamcity",
            "branch": "dev"
        }
    ]
}

rollbackBuilds

If you are using Circle, you will need to add a flag to your config: useBuildName: true to ensure that the tool gets the right build out of the API.

{
"rollbackBuilds":[
        {
            "buildName": "release-documentation-cli",
            "ciTool": "teamcity",
            "branch": "dev"
        },
        {
            "buildName": "release-documentation-cli",
            "ciTool": "circle",
            "branch": "master",
            "useBuildName": true
        }
    ]
}

releaseDetails

When booking releases you will need the following 'releaseDetails' object within your config:

"releaseDetails": {
    "emailAddress": "tools@news.co.uk",
    "title":  "The Times",
    "platform":  "Web",
    "osType": "Web",
    "partner": "internal",
    "priority": "P2 - Very Important release required (3-4 days)",
    "businessJustification": "Improvements to the site",
    "testingMethod": "both",
    "testingToolsUsed": "lots",
    "releaseDurationMinutes": 10,
    "releaseBookingJobLink": "<Link to ci job for approving and booking the release>",
    "appIds": ["id"],
    "environment": "environment"    
}

This creates a standard change record in ServiceNow for News UK digital application stack deployments. The change is linked to the Application Service matching the first appId in the array, with any additional appIds added as Affected CIs. If the emailAddress matches a user record in ServiceNow that is a member of the assignment group for the primary CI, the change will be assigned to them, otherwise it will be unassigned in the assignment group queue. The change will be set to the 'Review' stage, awaiting closure.

For creating change requests with ServiceNow you will need to set the following environment variables:

SN_USERNAME - ServiceNow username SN_PASSWORD - ServiceNow password SN_ENVIRONMENT - ServiceNow endpoint, set newscorpqa.service-now(QA) or newscorp.service-now(PROD)

Supported CI platforms

Release Cli currently supports jenkins, bitrise, teamcity and buddybuild for builds, testEvidenceJobs and rollbackBuilds. Examples of how to use the various CI tools can be found below.

"builds":[{
            "ciTool": "bitrise",
            "buildName": "release-documentation-cli",
            "buildSlug": "6e41921381d9a967",
            "workflow": "publish"
        },
        {
            "buildName": "release-documentation-cli",
            "ciTool": "teamcity"
        },
        {
            "buildName": "release-documentation-cli",
            "ciTool": "buddybuild"
        },
            "buildName": "ci-tests",
            "ciTool": "jenkins",
            "artifacts": ["testcoverage.html"]
        }]

Run

Get the Latest Release

command: release latest

This command prints the latest release version found on the projects Github releases page. It will also recommend the next release version based on the current commits.

Optional Parameters

Raw

parameter: -r --raw

Return the raw value (e.g. 'v1.1.1').

Get the Latest Pre-release

command: release latest-pre-release

This command prints the latest prerelease version found on the projects Github releases page.

Optional Parameters

Raw

parameter: -r --raw

Return the raw value (e.g. 'v1.1.1').

Get Next Release Version

command: release next-version

This command prints the next release version. (e.g. 'v1.1.1')

Create a New Release

command: release new

This command will guide you through creating a new Github release. Before running this command you will need to tag your latest release using git tags. Note you do not pass a version into this command.

Workflow:

git tag v1.0.1
git push origin v1.0.1
release new

Optional Parameters

Book Release

parameter: -b --bookRelease

Schedule the release within the DigiOps spreadsheet and create a change request in ServiceNow.

You will need to enter test evidence within your release-documentation-cli.config.json.

If you do not wish to be prompted for details of the change request you may use the additional parameter -s for scheduling the time of release.

Debug

parameter: -d --isDebug

Instead of booking real releases in the production google sheet and ServiceNow, post rows to the debug google sheet (found next to the the production sheet).

Useful when first setting up booking releases.

Product Owner

parameter: -p --productOwner

Pass in the product owner responsible for the release. Use the -x or --awaitingApproval instead to have this field filled out only after the product owner has approved the release.

Await Approval

parameter: -x --awaitingApproval

This option will set the product owners name to AwatingApproval in the release documents. This can then later be updated with the name of the product owner, using the approve command.

Scheduled

parameter: -s --scheduled

When passing this parameter the release will automatically be scheduled for release using the current date/time.

Skip Release Notes

parameter: -r --skipReleaseNotes

When passing this parameter the additional release notes question will be skipped.

Run on CI Pipeline

parameter: -c --runOnCi

When passing this parameter the additional release notes question will be skipped AND the release will be automatically scheduled using the current date/time.

Filter Release Tags

parameter: -f --tagFilter <tagFilter>

This parameter allows you to generate a release against custom, prefixed tags. For example, a release changelog cannot be created between tag 'project@1.0.0' and 'project@1.0.1', but after applying the tagFilter 'project@', a release changelog will be generated.

Version Tag Range

parameter: -v --versionTagRange <olderTag>..<newerTag>

This command allows you to generate a release between two version tags.

Use local changelog

parameter: -g --localChangelogPath

This parameter allows you to use your local changelog instead for the release notes generation. To use this parameter, simply set the value of this parameter to the path where your custom changelog is stored.

Update an Existing Release

command: release update

This command will update the latest release by default. This will provide you with the ability to modify the ChangeLog and release details using 'vi'.

Optional Parameters

Email Service

parameter: -es --emailService

Enables support of different types of email via nodemailer (the package we use for email in release cli). This defaults to gmail to maintain backwards compatability.

Email From

parameter: -ef --emailFrom

Sometimes the email user will not be an email address e.g. aws ses and in this case you need an email from address.

Version Tag

parameter: -v -versionTag [version]

When passing this parameter you can specify a different release version to update.

Mark Release as Latest

parameter: -r --release [version]

When this option is provided it will mark the latest release as 'latest', rather than 'prerelease' if the release had not previously been approved by the product owner.

Promote Release to Latest

command: release promote

This command will automatically mark the release as 'latest', rather than 'prerelease'. Use this command when a scheduled release has been released to production.

Optional Parameters

Version Tag

Promote a specific pre-release

parameter: -v --versionTag

Filter Release Tags

parameter: -f --tagFilter <tagFilter>

Running this command will filter out the tags which contain the non-numerical prefixes for example "@newsint@" in tag "@newsint@1.1.1" then promote the release.

Rollback Release to prerelease

command: release rollback

This command will automatically roll back the 'latest' release to be 'prerelease'

Optional Parameters

Version Tag

parameter: -v -versionTag [version]

When passing this parameter you can specify a different release version to promote.

Bump Version

command: release bump-version

This command will tag the release based on the committed changes since the last tagged release.

List Tags

command: release list-tags

This command will list all the tags.

Optional Parameters

Filter Release Tags

parameter: -f --tagFilter <tagFilter>

Running this command will only list the tags with the tag filter in their names.

Generate Change Log

command: release changelog

Running this command will generate the changelog between the current tag and the last tagged release.

Optional Parameters

Version Tag Range

parameter: -v --versionTagRange <olderTag>..<newerTag>

With this option you can generate the changelog between a chosen range.

Filter Release Tags

parameter: -f --tagFilter <tagFilter>

This parameter allows you to generate a changelog against custom, prefixed tags. For example, a release changelog cannot be created between tag 'project@1.0.0' and 'project@1.0.1', but after applying the tagFilter 'project@', a release changelog will be generated.

Book a New Release

command: release book

This command will guide you through booking a new release in the DigiOps Google sheet.

Workflow:

release book --productOwner TomPallister --versionTag @newsint/nu-sun-urban-airship-notification@0.1.0

You will need to enter test evidence within your release-documentation-cli.config.json

Required Parameters

Product Owner

parameter: -p --productOwner

Pass in the product owner responsible for the release

Version Tag

parameter: -v --versionTag

When passing this parameter you specify a release version to book.

Optional Parameters

Debug

parameter: -d --isDebug

Instead of booking real releases in the production google sheet, post rows to the debug google sheet (found next to the the production sheet).

Useful when first setting up booking releases.

Send a Release Notification Email

command: release email

This command will guide you through sending an email to notify stakeholders of an upcoming release or a completed release.

Workflow:

release email --type notify-starting --versionTag @newsint/nu-sun-urban-airship-notification@0.1.0 --emailUser "x@x.com" --emailPass "foo" --emailRecipients "foo@bar.com, bar@foo.com"

You must have the following object in release-documentation-cli.config.json

Please provide the same details as you would provide in your 'Release Request Form'.

"releaseDetails": {
    "emailAddress": "tools@news.co.uk",
    "title":  "The Times",
    "platform":  "Web",
    "osType": "Web",
    "partner": "internal", // 'internal' ( NewsUK Teams) or custom partner
    "priority": "P2 - Very Important release required (3-4 days)",
    "businessJustification": "Improvements to the site",
    "testingMethod": "both", // 'manual', 'automated' or 'both'
    "testingToolsUsed": "Mocha, AyeSpy, WDIO",
    "releaseBookingJobLink": "<Link to ci job for approving and booking the release (required for po-approval email type)>"
}

You must have a gmail account that can be used to send email via SMTP and it must have the option here selected.

Required Parameters

Type

parameter: -t --type

When passing this parameter you specify the type of email to send either notify-starting, notify-completed or po-approval.

Gmail Username
Version Tag

parameter: -v --versionTag

When passing this parameter you specify a release version to email.

Gmail Username

parameter: -u --emailUser

When passing this parameter you specify a username for node to use when sending emails via Gmail.

Gmail Password

parameter: -p --emailPass

When passing this parameter you specify a password for node to use when sending emails Gmail.

Email Recipients

parameter: -e --emailRecipients

When passing this parameter you specify the email addresses to send the release notification to.

Create a Change Request

command: create-change-request

This command will create a change request in ServiceNow

Optional Parameters

Email Service

parameter: -es --emailService

Enables support of different types of email via nodemailer (the package we use for email in release cli). This defaults to gmail to maintain backwards compatability.

Email From

parameter: -ef --emailFrom

Sometimes the email user will not be an email address e.g. aws ses and in this case you need an email from address.

Scheduling

parameter: -s --scheduled

This parameter will automatically calculate the scheduled start and finish time of the change based on the current time and the releaseDuration specified in the ReleaseDetasils part of the config file.

Update the Github release details

parameter: -u --updateGitRelease

This parameter will ensure that the Github release details are updated to include the change request ID.

Specify version to make change request for

parameter: -v --versionTag <versionTag>

This parameter will allow you to choose which release to make the change request for.

Approve a release

command: approve

This command will amend any release, that has been created with the -x or --awaitingApproval options selected, with the name of the product owner specified.

Required Parameters

Product Owner

parameter: -a --productOwner <productOwner>

use this flag to specify the name of the product owner.

Development

npm install or yarn to get the dependencies

npm run build or yarn build to build the project (must be done when making changes)

npm link to run locally

Test

npm run test:unit or yarn test:unit to run the unit tests with coverage

npm run test:integration or yarn test:integration to run the integration tests using the ServiceNow API

Readme

Keywords

none

Package Sidebar

Install

npm i release-documentation-cli

Weekly Downloads

2,763

Version

5.2.4

License

BSD-3-Clause

Unpacked Size

887 kB

Total Files

82

Last publish

Collaborators

  • news-tools
Try on RunKit
Report malware