release-documentation-cli
Advanced tools
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
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.
Releases should include a changelog with the following inofrmation:
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.
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.
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.
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.
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
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
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
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:
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",
}
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",
}
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
}
]
}
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"
}
]
}
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
}
]
}
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)
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"]
}]
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.
parameter: -r --raw
Return the raw value (e.g. 'v1.1.1').
command: release latest-pre-release
This command prints the latest prerelease version found on the projects Github releases page.
parameter: -r --raw
Return the raw value (e.g. 'v1.1.1').
command: release next-version
This command prints the next release version. (e.g. 'v1.1.1')
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
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.
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.
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.
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.
parameter: -s --scheduled
When passing this parameter the release will automatically be scheduled for release using the current date/time.
parameter: -r --skipReleaseNotes
When passing this parameter the additional release notes question will be skipped.
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.
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.
parameter: -v --versionTagRange <olderTag>..<newerTag>
This command allows you to generate a release between two version tags.
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.
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'.
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.
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.
parameter: -v -versionTag [version]
When passing this parameter you can specify a different release version to update.
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.
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.
Promote a specific pre-release
parameter: -v --versionTag
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.
command: release rollback
This command will automatically roll back the 'latest' release to be 'prerelease'
parameter: -v -versionTag [version]
When passing this parameter you can specify a different release version to promote.
command: release bump-version
This command will tag the release based on the committed changes since the last tagged release.
command: release list-tags
This command will list all the tags.
parameter: -f --tagFilter <tagFilter>
Running this command will only list the tags with the tag filter in their names.
command: release changelog
Running this command will generate the changelog between the current tag and the last tagged release.
parameter: -v --versionTagRange <olderTag>..<newerTag>
With this option you can generate the changelog between a chosen range.
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.
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
parameter: -p --productOwner
Pass in the product owner responsible for the release
parameter: -v --versionTag
When passing this parameter you specify a release version to book.
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.
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.
parameter: -t --type
When passing this parameter you specify the type of email to send either notify-starting, notify-completed or po-approval.
parameter: -v --versionTag
When passing this parameter you specify a release version to email.
parameter: -u --emailUser
When passing this parameter you specify a username for node to use when sending emails via Gmail.
parameter: -p --emailPass
When passing this parameter you specify a password for node to use when sending emails Gmail.
parameter: -e --emailRecipients
When passing this parameter you specify the email addresses to send the release notification to.
command: create-change-request
This command will create a change request in ServiceNow
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.
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.
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.
parameter: -u --updateGitRelease
This parameter will ensure that the Github release details are updated to include the change request ID.
parameter: -v --versionTag <versionTag>
This parameter will allow you to choose which release to make the change request for.
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.
parameter: -a --productOwner <productOwner>
use this flag to specify the name of the product owner.
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
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
FAQs
## Overview
The npm package release-documentation-cli receives a total of 424 weekly downloads. As such, release-documentation-cli popularity was classified as not popular.
We found that release-documentation-cli demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.