Release Notes Application
 | Manages Release Notes for software products (creation, reports) |
| Type | XAR |
| Category | Application |
| Developed by | |
| Active Installs | 8 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Compatibility | Version 2.1 requires XWiki 14.10+ |
Table of contents
Description
Accessing the application
The Application can be accessed from the Application Index or from the Applications Panel.
From Applications Panel
Home Page
From the home page of the application, you can:
- see existing release notes
- create a new release notes
- generate custom reports
Example of a generated Release Note:
Adding Changes
A Release Notes is composed of changes. Each change is created as a page and the changes are then displayed inside the Release Note page using either the {{changes.../}} or the {{releasenotechanges/}} macros (see below for more details on those macros).
Right now, to add a new change, you need to navigate to ReleaseNotes.Data.WebHome. In the future you'll be able to add changes directly from the Release Note pages.
Example of viewing a given change:
Custom Reports
The application home page (and the Changes home page) offer the ability for users to generate their own custom Release Note change report. This is useful for example if you wish to see, for example, all user-related changes that happened between 2 product versions.
The form allows to choose the displayer to use. Currently we provide the following displayers:
- Grid Displayer
- Flow Displayer
- Simple Displayer
- List Displayer
Macros
The following macros are made available.
{{getChanges}}
Get Release Notes change items and store them in a variable.
Usage:
Where:
- products: (Optional) The product for which to get changes for, e.g. XWiki. Defaults to all products.
- versions: (Optional) The comma-separated list of versions for which to get changes, e.g. 1.2,2.5. Defaults to all versions.
- audience: (Optional)The audience for which to get changes for, e.g. user. Defaults to all audience.
- containsScreenshots: (Optional) Whether we include only changes with screenshots or not, e.g. true. Default to all changes (with and without screenshots)
- contextVariable: (Mandatory) The variable name that will contain the list of release note change document references (as String), i.e. documents containing a ReleaseNotes.Code.Change.ChangeClass xobject.
Also note that HQL LIKE wildcards are allowed (e.g. ? and % characters). The >, <, >= and <= characters are also supported at a start of a numeric value (e.g. for versions).
Full Example:
{{velocity}}
#foreach ($changeDoc in $changeDocs)
* $changeDoc
#end
{{/velocity}}
{{displayChanges}}
Display Release Notes change items.
Usage:
Where:
- displayer: (Optional) The type of display to use to display the changes. Valid values are list, grid, flow, simple. Default is grid#. Note that you can create your own displayer since the default behavior is to include a displayer document located at <space where the app is installed, e.g. ReleaseNotes>.Code.Change.ChangeDisplayer<Capitalized displayer name>.
- displayEditLink: (Optional) Whether to display a link to directly edit the change. Defaults to false
- contextVariable: (Mandatory) The variable name containing the list of document reference strings pointing to documents containing a ReleaseNotes.Code.Change.ChangeClass xobject.
{{releasenotechanges}}
Display a full release notes for a product, version, etc, by reading an xobject from the current page having the following xproperty names:
- product
- version. In addition the version is also extracted from the current document's parent reference. TODO: Clarify this.
- released (whether the version has been released already or not)
Usage:
Parameters:
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| exclusions | Yes | Comma-separated list | N/A | ReleaseNotes Application 2.1+ List of change references to exclude, e.g. ReleaseNotes.Data.XWiki.14\.9RC1.Entry002.WebHome, ReleaseNotes.Data.XWiki.14\.9RC1.Entry003.WebHome |
Configuration
When adding a new release notes, the template used is the one defined in the ReleaseNotes.Code.ReleaseNotesConfig page's xobject which allows to configure:
- the default product name (used on the home page to pre-fill the form to add a new release note)
- the reference to the template to use.
Creating a Template
When creating a release notes template, two velocity bindings are available to the template content:
- product: the name of the product
- version: the short version
Creating a Displayer
It's possible to add new Displayers. To add one, create a page at ReleaseNotes.Code.ChangesDisplayer<id> where <id> is the id of your new displayer. For example the Grid Displayer use the id Grid and is available at ReleaseNotes.Code.ChangesDisplayerGrid.
Inside your displayer page you can:
- Include the ReleaseNotes.Code.DisplayerMacros page which has a few velocity Macros and some variables to help you
- Access Velocity bindings:
- changeItems: list of references to change pages to display
- All {{changes}} macro parameter values: audience, products, versions, categories, importance, containsScreenshots, displayEditLink
Example (code for the Simple Displayer):
{{velocity}}
## Inputs:
## - $changeItems
## - $displayEditLink
#foreach ($item in $changeItems)
#set ($changesDoc = $xwiki.getDocument($item))
#generateDisplayEditLink($$displayEditLink, $changesDoc)
=== $changesDoc.getValue('title')${displayEditLinkMarkup}===
$changesDoc.getValue('summary')
#displayScreenshots($changesDoc, true, false)
#set ($description = $changesDoc.getValue('description'))
#if ("$!description" != '')
[[More details>>doc:$changesDoc.documentReference]]
#end
#end
{{/velocity}}
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Release Notes
v2.2.1
v2.2
v2.1
v2.0
Dependencies
Dependencies for this extension (org.xwiki.contrib.releasenotes:application-releasenotes-ui 2.2.1):
- org.xwiki.platform:xwiki-platform-rendering-macro-velocity 14.10
- org.xwiki.rendering:xwiki-rendering-macro-html 14.10
- org.xwiki.platform:xwiki-platform-sheet-ui 14.10
- org.xwiki.platform:xwiki-platform-livetable-ui 14.10
- org.xwiki.platform:xwiki-platform-rendering-wikimacro-store 14.10
- org.xwiki.platform:xwiki-platform-panels-ui 14.10
- org.xwiki.platform:xwiki-platform-rendering-macro-gallery 14.10
