Creating a Custom Release Notes Template Containing Release Comments
Many JIRA users want to expand the generated Release Notes to include release comments for each issue in the report. Thistutorial shows how to do this using a custom field and some customized velocity templates. It assumes the reader understands JIRA's custom fields. For more information on custom fields see the JIRA documentation.
Note, this tutorial applies to JIRA Server only.
Step 1: Creating a Custom Field
The first thing to do is add a custom field for your release note comments, as described below. Note, you'll be associating this custom field with a screen; you can use the default screen or create your own beforehand.
- In JIRA, click the cog icon > Issues.
- Click Custom fields in the left menu.
- Click Add custom field to start the add custom field wizard. Create a field with the following details:
- Type: Text Field (multi-line)
- Name: Release notes comments
- Description: This is a comment to include on the generated release notes.
- Associated screens: Resolve Issue Screen
- Click Update to create your custom field.
You have now finished creating a custom field that will be displayed when you resolve or close an issue. We'll use this to enter comments to appear on the release notes.
Step 2: Creating Custom Velocity Templates for Release Notes Reports
Velocity is the templating engine used in JIRA. Currently JIRA ships with a text and a html release notes report template. For this tutorial we will modify the existing templates to also display the custom field that we created in the previous step, for each issue in the report. The modified text template looks something like this:
The modified html template looks like this:
The only difference between the above templates and the originals is the definition of the velocity macro 'getReleaseNoteComment' and its use after the issue summary. In the macro we use the context variable $customFieldManager which is an instance of the com.atlassian.jira.issue.CustomFieldManager interface. We use the CustomFieldManager to get all CustomFieldObjects for the current issue and then iterate through them looking for the field we want. When we find the field named 'release notes comments' we get and display the value if it is not null. NOTE: we do not use the getCustomFieldObjectByName method because it is deprecated and we can not be certain that the custom field name will be unique within the JIRA instance.
These velocity templates will display the 'release notes comments' custom field in our generated Release Notes. Now you need to tell JIRA to use the new templates.
Step 3: Modifying JIRA to Use Custom Velocity Templates
Deploying Velocity Templates without a Restart
In a development instance, you can play with picking up velocity file changes without a restart.
- Change class.resource.loader.cache from true to false
- Uncomment (remove the # sign from) #velocimacro.library.autoreload=true
Keep in mind that the next time you upgrade JIRA – or need a new installation for any reason – you will have to manually copy any changes you have made to the JSPs or tempates into the new installation of JIRA. If the JSPs or templates have changed in the newer version, you will have to port your customization into them.
This is quite a simple step. Place the two velocity templates into the
<jira-application-dir>/WEB-INF/classes/templates/jira/project/releasenotes subdirectory of your JIRA Installation Directory.
Next you need to specify your new template formats by changing the value of the
jira.releasenotes.templates property in the
jira-config.properties of your JIRA Home Directory.
- There is no need to modify the
- we still want an Html and Text option and
- we have only changed the templates themselves.
jira.releasenotes.templatesproperty value should changed to look something like the following, representing your new Html and Text Velocity template files, respectively:
See Adding a New Format Template for more information and how to define these properties if they do not already exist in your
Save your modified
jira-config.properties file and restart JIRA. Now we can test that what we have done works. You must make sure you can generate some Release Notes that will contain issues:
- Make sure that you have created a version for the project you are testing this under (release notes can only be generated for a version).
- Make sure that you have some issues that have the fix versions set to the version you created above.
- Make sure that you have entered some release comment text on the issues with the fix versions from above(in our example if there is not a release comment for an issue then nothing will display and it will look very much like the original Release Notes).
Browse to the release notes page, click the 'Browse Project' link in the top navigation, click the 'Release Notes' link on the resulting page, choose your 'Version' and 'Style', and click 'Create'. You should see the release note comments text after the summary text for each issue. The screen should look something like this:
Step 4: Filtering Release Notes
As an optional extra, you can filter the release notes based on various issue properties to see if they match your criteria. For example, to print only issues that have a resolution of Fixed and a Status, put an
#if statement around the code that creates a bullet point for the issue:
This tutorial shows a very simple modification to the Release Notes reports but the concepts used within should show you how to customize Release Notes to fit many other needs. The use of custom fields and the mechanism for accessing their values through a velocity template can allow a great number of extensions beyond the scope of this example.
Have fun and good luck!
1) Available Fields - Please see the JIRA Remote API for details on what information you can retrieve. For example:
2) Template Syntax - The Velocity User Guide will help you choose the right syntax.
3) Help & Support - Please post to the JIRA Development Forums for get help from the user community with your templates.