Release notes files help to keep track of the changes made for a specific content entity like an integration or a playbook.
To generate a release notes markdown file, first commit the changes to your branch and then run the following command provided by the
Please note: Changes which have not been committed will not be detected automatically by the
This command will bump the
currentVersion found in
pack_metadata.json file automatically according to the update version (as denoted by the
-u flag) for you.
Generally, you will use the command when you are ready to merge and expect no other changes. If you need to make additional
changes after running the command, you will need to remove the
-u argument. This will update the release notes
file for you to fill out.
For more detailed information regarding the
update-release-notes command in the
demisto-sdk, please refer to the
documentation found here.
The release notes file will be generated for you and is found under the
ReleaseNotes folder within each pack. If this folder does not already exist, one will be created for you.
The names for the files generated should not be changed as this will cause potential issues in the future.
After running the
demisto-sdk command mentioned above, the release notes file which was generated will contain 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 were detected in the Cortex XDR pack for the items IncidentFields, Integrations, and Playbooks; the following would be 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:
One should specify in the corresponding release notes file the following changes:
- Any change made
- Creation of a new command
- Adding/updating parameters
- Adding/updating arguments
- Updating outputs
- Fixes for customer bugs
The release notes need to be in simple language and informative. Think about what is the impact on the user and what they should know about this version.
- 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:
If this is a single line release note, there is no need for the bullet point, just a regular sentence.
Pretend you need this release note to do your work. A bad RN can easily lead to a CS ticket.
- Command name: - should be wrapped with three stars - ***command_name***
- Packs/Integrations/scripts/playbooks and other content entities (incident fields, dashboards...) - should be wrapped with two stars - **entity_name**
- Parameters/arguments/functions/outputs names - should be wrapped with one star - *parameter_name*
Note: Use these if the change has no visible impact on the user, but please try to refrain from using these if possible!
Release notes are required to contain all items which have been changed included in the generated file. As such, validation will fail 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. To solve this, you may comment out the entries by using the following syntax:
demisto-sdk includes the
doc-review command to assist with the doc review process. It will check 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 (although we try to avoid it as much as possible, sometimes it is needed). From XSOAR version 6.5 and above, there is a support to mark a new version as a breaking changes version mechanism.
Marking a version as a breaking changes version will pop up a screen to the customer upon installation:
In order to specify the new introduced version as breaking changes, the demisto-sdk update-release-notes command can be run with the -bc flag, for example:
-bc flag will:
- Generate 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 will be created in the corresponding ReleaseNotes directory.
- The configuration JSON file will be generated with the following fields:
breakingChanges: Indicates whether version is breaking changes or not, will be created with
truevalue upon using
breakingChangesNotes: Will contain the text to be displayed to the customer upon installation, as can be seen in above image. If
breakingChangesNotesis not specified, the default will be to present the whole release notes text to the user upon installation.
Make sure to remove the
%%UPDATE_RN%% from the generated file and leave the other generated items intact.
When I run the
update-release-notes command, it does not find any of my changes.#
First make sure you have committed your files. Next check to see 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 bumped. To resolve this, delete
the generated release notes Markdown (*.md) file and restore the
currentVersion in the
pack_metadata.json file to it's original version. Next, pull from the master branch.
Lastly, run the
update-release-notes command as you previously had done.
New packs do not require release notes. The build process will automatically create the initial release notes for you.