Usage
Information collected by ReleaseFab is stored in an XML-file which can be opened with ReleaseFab. Such files can be used as startup files to be opened as soon as ReleaseFab is launched with that configuration. ReleaseFab uses settings with different scopes. These scopes are user, project and volatile. Startup files are usually configured per project. An example can be found in the file projectconfig.xml of ReleaseFab itself.
The following settings can be configured in settings.xml and projectconfig.xml:
| Key | Content | Type [GENERAL, USER, PROJECT, VOLATILE] | Data Type |
|---|---|---|---|
| PROJECT_FILE_NAME | Name of file with project settings | GENERAL | String |
| PROJECT_FILE_PATH | Directory containing PROJECT_FILE_NAME | GENERAL | String |
| USER_SETTINGS_FILE | Name of file with user settings | GENERAL | String |
| USER_SETTINGS_PATH | Directory containing USER_SETTINGS_FILE | GENERAL | String |
| STARTUP_FILE | Path to the file loaded at startup | PROJECT | String |
| ALM_STATUS | Status allowed by the ALM system | PROJECT | List<String> |
| ALM_IMPORT_STATUS | Status allowed to be imported from the ALM system | PROJECT | List<String> |
| ALM_EXPORT_STATUS | Status allowed to be exported | PROJECT | List<String> |
| ALM_SERVER | URL of the ALM server | PROJECT | String |
| ALM_USER | Username for the ALM server | USER | String |
| ALM_PASSWORD | Password of ALM_USER for the ALM server | VOLATILE | String |
| ALM_CERTIFICATE_PATH_WINDOWS | Path containing the ALM server certificate on Windows machines | PROJECT | String |
| ALM_CERTIFICATE_PATH_LINUX | Path containing the ALM server certificate on Linux machines | PROJECT | String |
| EXPORT_ORDER | Order in which information is exported by the plugins | PROJECT | List<CCLTuple> |
| VIEW_ORDER | Order in which the plugins are shown in the UI | PROJECT | List<CCLTuple> |
| COMMIT_TEMPLATE | VCS commit template in specific notation | PROJECT | String |
The following parameters and flags can be set:
| Key | Description | Example | Optional |
|---|---|---|---|
| -cli | Start command line interface | -cli | yes |
| -docbook | Generate docbook when using the CLI | -docbook | only when using the GUI or other task |
| -customerdocbook | Generate docbook for customer when using the CLI | -customerdocbook | only when using the GUI or other task |
| -help | Show help text | -help | only when using the GUI |
| delivery_name | Creates a new delivery under that name | delivery_name=2.3.5 | yes |
| source | Directory containing XML file with version information | source=C:\user\project | no |
| config | Directory containing projectconfig.xml | config=C:\user\project\config | yes, requires specific project structure |
| generalsettings | Directory containing settings.xml | generalsettings=C:\user\project\settings | yes, requires specific project structure |
| user | Username for Application Lifecycle Management plugins | user=JohnDoe | only when using the GUI |
| pw | Password for Application Lifecycle Management plugins | pw=SecurePassword | no |
| resultfile | Filepath to save the generated docbook file to | resultfile=./result.xml | only when not exporting docbook |
| from | Delivery to start with when exporting docbook | from=2.1.0 | only when not exporting docbook |
| to | Delivery to end with when exporting docbook | to=2.3.5 | only when not exporting docbook |
ReleaseFab can be used via the command line. Therefore the assignment strategies and their parameters need to be set in the XML-file containing version information.
The following command creates a new delivery called 2.7.8 and saves it to the XML-file in the source directory:
ReleaseFabRuntime.bat|sh -cli source=C:\user\project config=C:\user\project\config generalsettings=C:\user\project\settings delivery_name=2.7.8
In order to export the information as docbook customize the following command:
ReleaseFabRuntime.bat|sh -cli source=C:\user\project config=C:\user\project\config generalsettings=C:\user\project\settings -docbook|-customerdocbook resultfile=./result.xml
When using an ALM plugin, user and pw need to be passed to the CLI as well.
Without the -cli flag the application will always launch the graphical user interface.
There are two basic usages of the application. Either the compiled artifacts are part of the project which needs to be documented in form of a submodule or ReleaseFab is used as a standalone application.
The structure needs to be setup as follows:
projectRoot
|---build_tools
| |---releasefab
| | |---bin
| | |---releasefab.bat|.sh
| | |---settings.xml
| | |---...
|---config
| |---projectconfig.xml
|---src
| |---...
As shown above the releasefab.bat|.sh needs to be copied from the downloaded artifacts to the root of the project to be documented.
In order to run ReleaseFab as a standalone application, the parameters generalsettings and config need to be set to the paths containing settings.xml and projectconfig.xml respectively. This can be done on the command line, or added to the ReleaseFab_Standalone.bat|.sh.
When there is no startup file configured in projectconfig.xml the application will launch with an empty project as shown in the image below.
ReleaseFab Empty Project
The tabs on the bottom represent each plugin which has been compiled. The strategies of how to import the information from these sources are configured per plugin and component on each of these tabs.
Software products in the view of ReleaseFab consist of components. This information shown in the Release Notes is different for every component. A project consists of at least one component, but can be as complex as a whole tree of components.
To get started a new component needs to be created. Optimally the root component of the software project you are documenting is created first. To do that right click on the empty table in the Info: Version tab and choose Add root component. By double clicking the name of the newly created component can be renamed according to your project.
To create more components right click the root component and select whatever action suits your needs. Components can be created:
- before the selected component
- as a subcomponent to the current component
- after the curent component
Components can also be removed as long as they do not have child components or contain any information on deliveries. Components can be marked as Customer Relevant to distinguish between Release Notes for customers and internal use.
By selecting File -> Save as... from the menu, the current release information can be saved to an XML-file. That file can be opened and set as the startup file for this project in the projectconfig.xml file.
Information gathered by the different plugins can be assigned through various strategies. They are selected from the drop-down menu on a component basis. When hovering over the strategies, a tool-tip on how to utilize these strategies and their parameters is shown. The button labeled with T tests the supplied parameters and shows its result in a new window.
Once all components and their assignment strategies are set up, it might be time to release a new version of your documented software.
In that case, select Action -> Add new delivery from the menu. Next enter the name of the delivery (can be the version number), adjust the creation date and time as well as the name of the integrator if necessary. If all the Assignment Strategies are setup correctly the newly created delivery will be shown as a new column in the Info: Version tab.
If something went wrong and you need to delete a delivery, select Action -> Remove delivery and choose the delivery you want to delete. As soon as you click OK the selected delivery will be deleted. However all changes made are only written to disk when hitting File -> Save or the corresponding icon.
ReleaseFabs functionality is mostly separated into plugins. This wiki only describes the plugins which are part of this repository. Plugins using the same version of the ReleaseFab Library as an API will be compatible with ReleaseFab. For the version number of the ReleaseFab Library consult the Release Notes of your version of the project. They are available on GitHub.
Custom plugins need to be linked to ReleaseFab via jlink. Therefore consult the development section of the Wiki.
The version plugin documents the version of every component of the component tree according to the configured assignment strategy. Mostly this value is retrieved by running a command through the Command Executor assignment strategy and parsing the version string from its output. The value can also be set using a constant text or other assignment strategies.
Important Information is a plugin used to document additional information which is important for the new release. This can include important steps to take when updating to that particular version or features which might have been discontinued which the user should know about before updating.
The Git plugin gathers all the commits of the local repository which have been made between the Git tag which is currently checked out and the tag before. If the current HEAD of the repository is not checked out to a tag, the documentation is stopped.
Git Commit information is parsed from the commit messages of your repository. The plugin needs to know the commit template used for the commit messages in order to be able to parse the information.
The following keys are supported:
- {short description} Short description of the changes made
- {itemID} ID of the item in the ALM system
- {yes} Marker if API-modifications have been made
- {no} Marker if no API-modifications have been made
- {internal doc} Documentation for internal purposes
- {external doc} Documentation for external purposes (customer)
- {reviewer} Name of the Reviewer
Only the {itemID} field is mandatory.
In order to configure the application with a custom commit template, just replace the parts of your commit template containing the information mentioned above with the corresponding keys.
Template:
description, #item-id, yes: , no: , internal documentation, external documentation, Reviewer
Actual Commit:
Test commit, #1234, yes:x, no: , Tested a commit, First commit, TestReviewer
ReleaseFab Commit Template Notation:
{short description}, #{itemID}, yes:{yes}, no:{no}, {internal doc}, {external doc}, {reviewer}
NOTE: The Git Plugin documents from the recent Git tag which the HEAD needs to be synced to to the Git Tag of the version before that. Tags need to be set with a message (e.g. git tag v1.0.0 -m "1.0.0")
If an implementation of an Application Lifecycle Management Service is available in the plugins folder, the corresponding items will be retrieved from the ALM service by their Item-ID and filtered by their status. Which statuses are allowed can be configured as a setting.
After being filtered the remaining Git Commits are sorted by the time they were commited and exported from newest to oldest.
The main purpose of the application is to export the information which was automatically gathered and export it as Release Notes. This can be done in the DocBook format. DocBook is a universal format, which can be converted into many different more readable formats (e.g. PDF, MD, HTML...). This is supported by tools like Pandoc and the Apache FOP.
Any export can be for a customer or not. This can be set for every component. When exporting for a customer only the components which are marked that way are part of the exported Release Notes. By default all components are part of the Release Notes for the customer.
When using File -> Export -> Export Deliveries the same file which is currently open is exported to a location which has to be selected. This is a useful way to make the current information available to other users.