Release notes files help users keep track of changes made for specific content entities, such as integrations or playbooks.
To generate a release notes markdown file, first commit the changes to your branch and then run the following command provided by the demisto-sdk:
Please note: Changes that have not been committed are not detected automatically by the update-release-notes command.
This command automatically updates the currentVersion found in the pack_metadata.json file according to the update version (as denoted by the -u flag). The versioning format is as follows: MAJOR.MINOR.REVISION.
|versioning type||when to use|
|major||When you make a new version of the pack, or one of its integrations (for example, a rewrite of integration, or a vast change in it).|
|minor||When you add functionality (for example mirroring, fetching incidents, or indicators), or when you add many commands.|
|revision||When you add new content items or a few commands, and when updating such.|
|documentation||When adding or updating documentation.|
In most cases, you run the command when you are ready to merge and expect no further changes. If you need to make additional
changes after running the command, remove the
-u argument. This updates the release notes file for you to fill out.
For more information regarding the update-release-notes command in the demisto-sdk, please refer to the command documentation.
The release notes file is generated for you and is found in the ReleaseNotes folder within each pack. If this folder does not already exist, it is created for you.
Do not change the names of the files that are automatically generated, as this can cause potential issues later in the development process.
After running the demisto-sdk command, the release notes file contains a section for each entity changed in the pack as well as a placeholder (
This placeholder should be replaced with a line describing what was changed for that specific entity.
For example, if changes are detected in the Cortex XDR pack for the items IncidentFields, Integrations, and Playbooks; the following is created:
For single line RNs, follow this format:
For single line RNs with a nested list, follow this format:
For multiline RNs, follow this format:
For multiline RNs with nested content, follow this format:
Specify in the corresponding release notes file:
- Any change(s) made
- New command(s)
- New or updated parameters
- New or updated arguments
- Updated outputs
- Bug fixes
Release notes should be simple, informative, and clearly written. Consider the impact of changes on the user and what they need to know about this version. A poorly written release note with inadequate information can lead to a Customer Support ticket.
- Bad example:
Added the timeout parameter.
- Good example:
Added the timeout parameter, which enables you to define the amount of time (in minutes) that the integration will try to execute commands before it throws an error.
- Bad example:
Single line release notes do not need a bullet point.
Release notes must start with one of the following prefixes:
Release notes not using one of these prefixes will generate an error when running
- Command names: - should be wrapped with three stars - command_name
- Packs/integrations/scripts/playbooks and other content entities (incident fields, dashboards. etc.) - should be wrapped with two stars - entity_name
- Parameters/arguments/functions/outputs names - should be wrapped with one star - parameter_name
Note: In most cases we will avoid having such release notes, use these only if the change has no clear or visible impact on the user.
Release notes must contain all changed items included in the generated file. As such, validation fails if detected items are removed from the generated release notes file.
However, you may encounter a scenario where certain changes are not necessary to document in the release notes. In this case, to pass validation, comment out the entries using the following syntax:
demisto-sdk includes the doc-review command to assist with the documentation review process. The doc-review command checks the spelling of the release notes and provide guidance if you are not using one of our standardized templates. Example usage:
More info is available at the demisto-sdk doc-review command README.
In some cases, a new version is introduced which breaks backward compatibility. From Cortex XSOAR version 6.8 and above, there is support to mark a new version as a breaking changes version.
Marking a version as a breaking changes version provides the user with an alert before installation:
To specify the new introduced version as breaking changes, run the demisto-sdk update-release-notes command with the -bc flag. For example:
Adding the -bc flag:
- Generates a corresponding configuration JSON file to the new release notes. For example, if the newly created release notes version is 1_1_0.md, a new configuration file 1_1_0.json is created in the corresponding ReleaseNotes directory.
- The configuration JSON file is generated with the following fields:
- breakingChanges: Indicates whether the version is breaking changes or not, is created with true value upon using -bc flag.
- breakingChangesNotes: Contains the text to be displayed to the customer upon installation, as shown in the above image. If breakingChangesNotes is not specified, the default is to present the entire release notes text to the user upon installation.
%%UPDATE_RN%% from the generated file and leave the other generated items intact.
First check you have committed your files. Then verify that the type of file you changed requires a release notes entry. TestPlaybooks, Images, README's and TestData don't require release notes.
On rare occasions, it's possible that the pack you are working on has already had the version updated. To resolve this, delete the generated release notes Markdown (.md) file and restore the currentVersion in the pack_metadata.json* file to its original version. Next, pull from the master branch. Lastly, run the update-release-notes command again.
New packs do not require release notes. The build process automatically creates the initial release notes.