Release Notes Application

Last modified by Vincent Massol on 2017/11/27 00:11

cogManages Release Notes for software products (creation, reports)
TypeXAR
CategoryApplication
Developed by

Vincent Massol

Active Installs11
Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1
Installable with the Extension Manager

Description

This release notes application is installed on xwiki.org and can be seen in action there.

Accessing the application

The Application can be accessed from the Application Index or from the Applications Panel.

applicationspanel.png
From Applications Panel

Home Page

From the home page of the application, you can:

homepage.png

Example of a generated Release Note:

releasenotes-example.png

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.

change-home.png

Example of viewing a given change:

change.png

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.

report.png

The form allows to choose the displayer to use. Currently we provide the following displayers:

  • Grid Displayer

    displayer-grid.png

  • Flow Displayer

    displayer-flow.png

  • Simple Displayer

    displayer-simple.png

  • List Displayer

    displayer-list.png

Macros

The following macros are made available:

  • {{changes products="..." versions="..." audience="..." importance="..." displayer="..." categories="..." containsScreenshots="true|false" columns="..." displayEditLink="true|false"/}}
  • {{releasenotechanges/}}

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.

config.png

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):

{{include reference="ReleaseNotes.Code.DisplayerMacros"/}}

{{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&gt;&gt;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:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

A Release Notes Demo application is also available and can be installed using the Extension Manager using advanced search and the org.xwiki.contrib.releasenotes:application-releasenotes-demo extension id.

Dependencies

Dependencies for this extension (org.xwiki.contrib.releasenotes:application-releasenotes-ui 1.4):

Tags:
Created by Vincent Massol on 2016/09/28 16:48
    

Get Connected