switchtrue/jirachangelogbuilder

Communicates with JIRA and generates a change log for a given JIRA Project Version

JIRAChangelogBuilder

Communicates with Atlassians JIRA and generates a changelog based on a customisable template file for a given JIRA query (JQL).

Compilation

Run 'mvn install' from the base directory to generate build/jira-changelog-builder.jar. This will also automatically execute the bundled test case.

Usage

From the command line:

java -jar jira-changelog-builder.jar <JIRA_URL> <JIRA_username> <JIRA_password> <JIRA_project_key> <version> <template_list> [<flags>]

Where the arguments are used as follows:

• <JIRA_URL>: The URL of the JIRA instance (e.g. https://somecompany.atlassian.net).
• <JIRA_username>: The username used to log into JIRA.
• <JIRA_password>: The password used to log into JIRA.
• <JIRA_project_key>: The key of the project in JIRA.
• <version>: Specifies up to which version the changelog should be generated.
• <template_root>: The path on disk to the directory containing the mustache template files. All files in <template_list> are relative to this path.
• <template_list>: A CSV list of paths to template files. Each templated changelog is saved into a new file which can be processed at a later stage.
• <flags> (optional): One or more of the following flags: * --jql "some arbitrary JQL": Append the given JQL to the issue filter. eg status = "Ready for Build". * --object-cache-path /some/path: The path on disk to the cache, if you do not use this, no cache will be used. Using a cache is highly recommended. * --debug: Print debug/logging information to standard out. This will also force errors to go to the standard out and exit with code 0 rather than 1. * --changelog-description-field "field_name": The name of the field in JIRA you wish to use as the changelog description field. If you do not use this, it will default to the summary field. * --changelog-file-name /some/path/filename: A CSV list of paths on disk to the files you wish to output the file changelogs to. If you do not use this, the file changelog will be written to changelog#.txt in the working directory by default (where # is the changelog file number). * --eol-style (NATIVE|CRLF|LF): The type of line endings you wish the changelog files to use. Valid values are NATIVE (system line endings), CRLF (Windows line endings) or LF (UNIX line endings). If you do not use this, the changelogs will use the default system line endings (NATIVE). * --version-starts-with "Version name prefix": Only display versions in the changelog that have a name starting with 'Version name prefix'. This cannot be used with --version-less-than-or-equal. This is useful for restricting what goes in the changelog if you are producing different version side-by-side. For example, if 'Version name prefix' is "ACME_1.3" then "ACME_1.3.1", "ACME_1.3.5" and "ACME_1.3.8" would all match whilst "ACME_1.1.8" and "ACME_1.4.9" would not. * --version-less-than-or-equal "Version name": Only display versions in the changelog that have a name less than or equal to 'Version name'. This cannot be used with --version-starts-with. This uses a Java string comparison (compareTo). This is useful for restricting what goes in the changelog if you are producing different version side-by-side. For example if 'Version name' is "ACME_1.3.8" then "ACME_1.3.1", "ACME_1.3.5" and "ACME_1.1.8" would all match whilst "ACME_1.3.9" and "ACME_1.4.9" would not.

Managing the Cache

When specifying --object-cache-path the Java objects used to store the changelog information for a single version are serialized. The cache will always be used for any version other that the current version that has been specified in <version> however sometimes you need to rebuild an older version from JIRA (i.e. the version has changed in some way). This can be done simply by removing the serialised file, this fill will be found in the path specified by --object-cache-path with a file name of <project>_<version>.ser where <project> and <version> match the command line agruments. The JIRAChangelogBuilder will then regenerate these as required.

Testing

In order to execute the unit tests properly (and build/install the program), you must create a file named testing.properties and place it in the base directory. In this file, add the following values:

• url = <URL> where <URL> is the web address of the JIRA instance.
• username = <username> where <username> is the username of a user that can access the JIRA instance.
• password = <password> where <password> is the password for the specified user.
• project = <project> where <project> is the identifier (key) of the JIRA project.
• version = <version> where <version> is the version up to which the changelog should be generated.
• versionstartswith = <starts_with> where <starts_with> is a substring (prefix) of a version for which the write will match on to decide which version to include. For example, if <starts_with> is "ACME_1.3" then "ACME_1.3.1", "ACME_1.3.5" and "ACME_1.3.8" would all match whilst "ACME_1.1.8" and "ACME_1.4.9" would not.
• versionlessthanorequal = <less_than_or_equal> where <less_than_or_equal> is a version name that you want to compare as a string and only include versions with a name less than or equal to this. For example if <less_than_or_equal> is "ACME_1.3.8" then "ACME_1.3.1", "ACME_1.3.5" and "ACME_1.1.8" would all match whilst "ACME_1.3.9" and "ACME_1.4.9" would not.

Tests can be manually executed by running 'mvn test' from the base directory.

jirachangelogbuilder's Issues

Remove the ant files

We're now using maven to build so we should remove the files left over from the ant build.

Consider providing the compiled jar

First of all, congratulations for this awesome project. We use successfully in our CI server.

I would like to suggest provide the latest compiled version so that we can download automatically every time we generate the changelog.

Template based changelogs

The output format of the changelog is currently hardcoded. It would be nice if it could also produce XML/HTML/etc. Consider using a mustache-like (http://mustache.github.io/) templating format. Pass the template to use as a command line flag so that the same changelog builder jar can be used in different circumstances.
Could have a default template of "default.tmpl" or similar.

Better error handling.

The following strack trace appeared to be raised when the specified project key was incorrect.

Can we try to catch this exception and make it more obvious what the issue is.

java -jar jira-changelog-builder.jar http://192.168.56.110:8080 **** **** Project 0.0.1 ./ plain-text.mustache.txt --debug
DEBUG 10:26:17: --debug flag found. Debug logging enabled.
DEBUG 10:26:17: Starting with parameters: 
  Version: 0.0.1
  JIRA Project Key: Project
  JIRA URL: http://192.168.56.110:8080
  JIRA username: ******
  JIRA password: *******
  Template files: plain-text.mustache.txt
DEBUG 10:26:17: Establishing JIRA API connection for generating changelog to http://192.168.56.110:8080.
DEBUG 10:26:18: Obtaining project information via JIRA API.
Dez 04, 2013 10:26:18 AM com.sun.jersey.api.client.ClientResponse getEntity
Grave: A message body reader for Java class java.lang.String, and Java type class java.lang.String, and MIME media type application/json;charset=UTF-8 was not found
Dez 04, 2013 10:26:18 AM com.sun.jersey.api.client.ClientResponse getEntity
Grave: The registered message body readers compatible with the MIME media type are:
application/json;charset=UTF-8 ->
  com.sun.jersey.json.impl.provider.entity.JSONJAXBElementProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONArrayProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONObjectProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONRootElementProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONListElementProvider$App
*/* ->
  com.sun.jersey.json.impl.provider.entity.JSONJAXBElementProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONArrayProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONObjectProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONRootElementProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONListElementProvider$General
  com.sun.jersey.json.impl.provider.entity.JacksonProviderProxy

Exception in thread "main" com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class java.lang.String, and Java type class java.lang.String, and     MIME media type application/json;charset=UTF-8 was not found
    at com.sun.jersey.api.client.ClientResponse.getEntity(ClientResponse.java:548)
    at com.sun.jersey.api.client.ClientResponse.getEntity(ClientResponse.java:505)
    at com.atlassian.jira.rest.client.internal.jersey.AbstractJerseyRestClient.invoke(AbstractJerseyRestClient.java:66)
    at com.atlassian.jira.rest.client.internal.jersey.JerseyProjectRestClient.getProject(JerseyProjectRestClient.java:49)
    at com.atlassian.jira.rest.client.internal.jersey.JerseyProjectRestClient.getProject(JerseyProjectRestClient.java:63)
    at net.foxopen.jira.changelog.JiraAPI.fetchVersionDetails(JiraAPI.java:99

Exception running the builder

I'm facing the following exception running the lasted release of the changelog builder:

java -jar jira-changelog-builder.jar http://192.168.56.110:8080 **** **** Project 0.0.1 ./ plain-text.mustache.txt --debug
DEBUG 10:26:17: --debug flag found. Debug logging enabled.
DEBUG 10:26:17: Starting with parameters: 
  Version: 0.0.1
  JIRA Project Key: Project
  JIRA URL: http://192.168.56.110:8080
  JIRA username: ******
  JIRA password: *******
  Template files: plain-text.mustache.txt
DEBUG 10:26:17: Establishing JIRA API connection for generating changelog to http://192.168.56.110:8080.
DEBUG 10:26:18: Obtaining project information via JIRA API.
Dez 04, 2013 10:26:18 AM com.sun.jersey.api.client.ClientResponse getEntity
Grave: A message body reader for Java class java.lang.String, and Java type class java.lang.String, and MIME media type application/json;charset=UTF-8 was not found
Dez 04, 2013 10:26:18 AM com.sun.jersey.api.client.ClientResponse getEntity
Grave: The registered message body readers compatible with the MIME media type are:
application/json;charset=UTF-8 ->
  com.sun.jersey.json.impl.provider.entity.JSONJAXBElementProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONArrayProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONObjectProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONRootElementProvider$App
  com.sun.jersey.json.impl.provider.entity.JSONListElementProvider$App
*/* ->
  com.sun.jersey.json.impl.provider.entity.JSONJAXBElementProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONArrayProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONObjectProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONRootElementProvider$General
  com.sun.jersey.json.impl.provider.entity.JSONListElementProvider$General
  com.sun.jersey.json.impl.provider.entity.JacksonProviderProxy

Exception in thread "main" com.sun.jersey.api.client.ClientHandlerException: A message body reader for Java class java.lang.String, and Java type class java.lang.String, and MIME media type application/json;charset=UTF-8 was not found
    at com.sun.jersey.api.client.ClientResponse.getEntity(ClientResponse.java:548)
    at com.sun.jersey.api.client.ClientResponse.getEntity(ClientResponse.java:505)
    at com.atlassian.jira.rest.client.internal.jersey.AbstractJerseyRestClient.invoke(AbstractJerseyRestClient.java:66)
    at com.atlassian.jira.rest.client.internal.jersey.JerseyProjectRestClient.getProject(JerseyProjectRestClient.java:49)
    at com.atlassian.jira.rest.client.internal.jersey.JerseyProjectRestClient.getProject(JerseyProjectRestClient.java:63)
    at net.foxopen.jira.changelog.JiraAPI.fetchVersionDetails(JiraAPI.java:99

More control required over ordering and what appears in the changelog.

Currently the changelog builder includes every version in JIRA with a release date prior to to the date on which the changelog builder is being run.

This is not ideal when multiple version are being produced in parallel and the changelog may include release information for future versions that are built but not yet released.

A mechanism should be provided to allow for the following items:

• Customisable control over exactly which issues are included in the changelog.
• Customisable control over what order version appear in.

Consider adding an option to append or prepend changelogs

We have a use case that every time we release a new version, the changelog is generated and appended to the the current one. Currently, we achieve that generating a new file and using command to merge them.

If you consider useful, I can work on that and open a pull request.

The changelog can be populated with some JIRA that are not ready for build

If a Fix Version is assigned to a JIRA prior to the 'Ready for build' stage (or to any similar stages), the changelog for that version will display those JIRAs.

Ability to limit the versions that appear in the changelog.

Currently the changelog builder always produces a changelog with a full history of all previous builds.

It would be good to offer additional arguments to be able to limit what comes out, it would be good to consider the following options:

• Number of versions (i.e. give me the current version plus the last 8)
• By Date (i.e. only go back in history as far as 2013-05-11 - provides a fixed time point)
• By duration (i.e. only go back in history 20 days from now or 2 weeks - provides a moving time point.)
• All (display everything, current behaviour)

It could possibly be handle by a single argument --history that could appear in the following distinct formats:

• Number of Versions: --history 8
• By Date: --history YYYY-MM-DD
• By Duration: --history 2w or --history 4d or --history 1y for day, week and year durations.
• All: --history ALL

The code could simply parse the value for the appropriate format and raise an exception if none of these are matched.

For backward compatibility the default options should be ALL.

Use Windows line endings in changelog files.

Generated changelog files are currently using Unix line endings, meaning opening a .txt changelog file using a Windows program like Notepad will not display the changelog in a neat format.

It would be ideal to use windows line endings (CR/LF) so that such files can be opened in Notepad and display a neatly formatted changelog.

Ability to pass variables to template

Sometimes is necessary to pass some dynamic data to be used in changelog's template. Passing parameters in the command seems a good way to achieve that (only scalar values).

jira-chagelog-builder ... foo=1 bar=http://acme.com

Reduce Number of API Requests

Currently the API is called to get a list of versions for a project, then get a list of issues for that version and then for each issue to get its details. I would be nice to reduce the number of requests made. Perhaps this is possible without the use of the JIRA API Java library and communication directly.

Cache policy

If a JIRA is failed and is now part of another release, the previous release's item cached still has this issue listed.

It would be great to update the cache policy to invalidate a cached element if one of the JIRA listed is updated.

Hangs when complete

Hi,

Firstly, thanks for this -- it's exactly what we've been after!

One issue we're seeing which makes this impractical to use in a continuous integration system is that it appears to hang when complete. I've tried this on both a Linux and a Windows system. With debugging enabled, it gets to the 'Done - Success!' line... but then requires a Ctrl+C to end.

Unfortunately, this causes the CI build to hang -- any help appreciated!

Thanks,
Chris

Ability to configure the field to use as the changelog description

Add a flag to specify the name of the JIRA filed to be used as the changelog description. currently it is hard-coded as "Changelog Description" with a fall back of "Summary".
The "Summary" fallback is fine.

generate the JavaDoc

As part of the maven build we should be generating the javadocs.

Use of any JIRA field in a template

Currently the JIRAChangelogBuilder requires a command line argument of "--changelog-description-field " to be provided in order to specify field name in JIRA that provide the issue deescription.

Instead it would be good if you could just use any field name in the template and the changelog builder would fetch the appropriate fields from JIRA.

for example:
{{ summary }}
{{ fixVersion }}
{{ changelogdescription }}
{{ epiclink }}

There would have to be a deterministic policy on how tag names are related to field names (maybe case-insensitive and strip spaces?).

As this will involve the parsing of the templates to determine the field names it would also be good to introduce special place holders that can be replaced with environment variables, for example:

{{ $(SOME_ENV_VAR) }}

See if there is any functionality similar to this already in mustache (my gut feeling is no) and identify the "best way" to name the variables.

Element ordering when multiple versions have been released the same day.

If multiple versions have the same release dates, those versions will be sorted by version number ascending instead of descending.

Sample output:

11-06-2013 XXX-2.9.006
Bug fix release for XXX-2.9.000
[...]

07-06-2013 XXX-2.9.003
Bug fix release for XXX-2.9.000
[...]

07-06-2013 XXX-2.9.004
Bug fix release for XXX-2.9.000
[...]

07-06-2013 XXX-2.9.005
Bug fix release for XXX-2.9.000
[...]

06-06-2013 XXX-2.9.002
Bug fix release for XXX-2.9.000
[...]

05-06-2013 SEWPAC-2.9.001
Bug fix release for SEWPAC-2.9.000
[...]

Build scripts

Create ant builds scripts for the project and get rid of the build directory containing the jars that is currently committed to git.