Skip to content

Release notes automation

Jump to bottom
Roman Ivanov edited this page Aug 28, 2015 · 18 revisions

Release notes creation could automated process, if admins mark issues by special labels during issue management, have to group events by 3 categories manually : "Breaking backward compatibility", "New", "Bug fixes", "Misc" (corresponding labels: "braking compatibility", "new feature", "bug" , "misc"). We need a tool that generate UL-LI content of sections label at example.

Release notes automation is set of tasks:

  1. Creation and usage of new category labels: "braking compatibility", "new feature", "bug" , "misc"

  2. Validation of last commit message to reference issue number

  3. Generator of XML section content for releasenotes.xml file

Creation and usage of new category labels

That is ease step, and could be done at github

Validation of last commit message to reference issue number

We could enforce commit message format by UT on travis, we will validate commit by running "mvn verify" or all Uts. if commit is created on local that will force user to make message as we require. Validation could be done by special UT that use JGit to analyse repo.

  1. format: ^Issue #\d*: .* \$ , ^Pull #\d*: .* \$

  2. WE NEED to treat ID of PR as Issue, as for github it is the same - they share number set. We have to expect commit without reference to issue number - minor updates ( that does not make sense to create issue to and creation of PR is equivalent of Issue creation). We should validate only last commit, as on travis there will be no "non-pushed" commits. We need to do suppression for commit messages by RegExp, default is "^(minor|config|infra|doc|spelling): .*" to let contributors avoid issue creation for minor changes lik private method rename or .... .

  3. Enforce single line comment

  4. We need an option to ignore certain user from validation, user names of them should be hardcoded in UTs - that will be a list of users who can commit with any message. It is required as some time admins has to resolve problem quickly without wasting time on issue creation and version bump (during release) also done without following to format described above.

  5. On test failure we should print to user all rules for message formats to let him fix message easily.

  6. enhancement: we need to recheck that issue number exists on github and it is open or closed no more then 1 month ago.

Generator of XML section content for releasenotes.xml file

  1. We always grab changes to Release notes from GIT commit messages, as we reflect actual changes, all other approach is error prone

  2. if issue is valid we ignore commit message and use Issue/PR tittle (as issue state what is wrong and commit message is tending to have what was fixed and how). Release notes need "what was wrong". We can always change message of Issue/PR to make release notes looks good. We can change PRs title and description at any time so we are OK to treat PR as Issue. So contributor can do PR, got a failure , update a commit and push in the same PR.

  3. What to do with commit that reference few issues? - rare case we could use commit message and change it manually if required (complete automation does make sense for now).

  4. We do not analyse/use PR description at all, we skip commit message if issue number is referenced (as we will use Issue/PR title).

5)user need to specify tag from which to start ReleaseNotes creation, here is how I do that now - https://github.com/checkstyle/checkstyle/wiki/How-to-make-a-release#before-starting

  1. need to squash multiple events that reference the same issue to one.

  2. no category label on issue - generate error and force admin to update issue with a lavel.

###Use-cases

We have PR from:

  1. from Issue - the simplest case, we just demand issue number to be present in all commits.

  2. from online changes (without clone)

2.1) done by admins - I do it very often, especially at README.md or any other text file (we could have ignore option for admins)

2.2) done by others - usually typo changes or smth minor, it will NOT be a problem as such changes only fail a build and Admins still have right to merge changes even build is failed at certain UT. Tool will ignore commits that commited by admins (trust/super users).

  1. from PRs (without issue, as contribution to non existing problem)example

3.1) for enhancements and minor refactoring - THAT will be a problem .

3.2) for problems in design - that will be ok , as it will force to pay attention problem and write UTs too, and state a reason of update.

3.3) for functional changes - UTs changes required so it is not a just throwing code at us , it do need UTs to keep 100% and even more extension of UTs even coverage is 100%. Any functional changes have to be UTed.

Future plans (not required for first implementation):

  1. issue have to exists on github (Do we need to check for open state ???? Some changes are done with reference to already closed issues as minor update but author still want to let others know context, or missed configuration changes or suppressions removal or .... It will be a build failure as PR number is know only after PR is sent and far after commit is created.!!!!!) Can we grab close date from Github API for certain issue? (if yes - that will help us to ignore referencing to closed issues during 1 week)

Misc

Examples from other projects:

Issue at the end of message: https://github.com/spring-projects/spring-framework/commit/36ed4df59df03082b510841e55511d02424b7e56

issue at the beginning: https://github.com/hibernate/hibernate-orm/commits/master https://github.com/adangel/pmd/commits/master

Clone this wiki locally