Robust, flexible release notes generation

[mockitoguy]

Why?

Release notes generation is one of the highlight features of Shipkit. This ticket describes steps we can take to make release notes more robust and flexible. If you decide to implement one of the steps, please create separate ticket for it, we only have ticket for the first step (#190).

How?

1. In order to make the notes more readable, sometimes we need to emphasize the version so that it stands out from other versions in the release notes. It is needed in Mockito project which pushes to Maven Central only specific version, as requested by the community (#190)

2. Task that generates release notes does not declare all its inputs and hence it can be harder to use for advanced use cases. Currently, “version” and “tagPrefix” inputs are hardcoded in the task implementation. Let's expose those properties as task properties marked with @Input. Release notes plugin would configure the values, so that the task no longer hardcodes them (#201).

3. The release generation task is implemented as a pair of tasks: preview task and separate update task. This approach makes the tasks hard to reuse. If someone wants to declare or reconfigure release notes generation at the task level, he needs to do it twice. You can see this problem in #190 - “emphasizeVersion” property needs to configured twice. To solve the problem, we can create single implementation of IncrementalReleaseNotes and use Gradle’s task parameter API to distinguish between preview mode and update mode. Here’s how would this work:

• preview release notes: ./gradlew updateReleaseNotes —preview
• update release notes: ./gradlew updateReleaseNotes If the task parameters API is internal, let's be on the safe side and just use project property:
• preview release notes: ./gradlew updateReleaseNotes -Ppreview (#205)

4. Allow templating of release notes. This is probably the most challenging task but it will offer ultimate flexibility. Imagine that the user can completely alter the generated content, or even generate to a different format like JSON. At the moment, this feature is not scoped to the level that any contributor can jumpstart to implementing it. Here's how the feature could work from the user's standpoint:

updateReleaseNotes.templateFile = “docs/release-notes.template”

• We need to identify a good template engine to use, perhaps we can use some Groovy goodness. Simplistic, String based token replacement templating would be most likely insufficient because we do have loops and conditional complexity in the current code that generates release notes content.

[jpkrohling]

As part of https://github.com/jaegertracing/jaeger-client-java/issues/536 , I'm giving this library a try and I think we could benefit from the support for templates you described under the point 4. It's not a blocker, but would be nice to keep using our own format.