generate release notes with consistent presentation

[prjemian]

As noted, create tool(s) to simplify the generation of release notes with a consistent style and format. Might consider reporting in these sections:

• Base Classes
• Application Definitions
• Contributed Definitions
• NXDL (XML) Schema
• Documentation
• Other

Subsections (for each) would be

• new additions
• changes
• work-in-progress
• items removed
• items marked as deprecated

For example, this issue, when complete, would be added under the Other section.

[prjemian]

Of the ideas mentioned in #577,

This (http://www.mehdi-khalili.com/better-git-release-notes) is a blog that bears some reading.

This project (https://github.com/GitTools/GitReleaseNotes) has no activity since 2016-10. Looks stagnant.

This project (https://gist.github.com/bradyholt/b40fa59b6c5a09fbf0d8) is a shell script to create a new pull request. It may have value for a new tool.

More ideas here:

• https://duckduckgo.com/?q=how+to+get+nicely+formatted+release+notes+for+a+GitHub+pull+request%3F&t=ffsb&dbexp=a&ia=web
• https://stackoverflow.com/questions/3523534/good-ways-to-manage-a-changelog-using-git#22492425

[prjemian]

example: https://github.com/JakeGinnivan/GitReleaseNotes/blob/master/ReleaseNotes.md

GitVersion uses semantic versioning

[prjemian]

Two separate goals (can coexist):

• provide text that appears with a specific release in the GitHub releases list
• keep a permanent file of all release notes by release, newest release first

[prjemian]

That's too many categories! Could be more concise.

• Pull Requests (include accepted or not)
• Issues
• Selected Commits

Likely these could be automatically generated through the GitHub API with a script, then edited judiciously to reduce noise and indicate which general area of the repository was affected.

[prjemian]

Of course, all this would be since the previous release.

[prjemian]

Such as: v3.2...master

[prjemian]

Command line: git log --oneline --decorate --color v3.2...master

[prjemian]

For the text added to a GitHub release, suggest only adding Pull Requests and Issues (selected) parts of release-history.md file.

[prjemian]

Could proceed with release but want to have working links, as indicated, first

[prjemian]

These categories:

• New Tags
• Pull Requests (include accepted or not)
• Issues
• Selected Commits

[prjemian]

This command gets the commits:

item	command
commits	git log --oneline --decorate --reverse v3.2...master
tags	git log --oneline --decorate --reverse v3.2...master | grep tag:

But command line git has no access to GitHub pull requests or issues. Needs some Python code that uses the PyGithub package. Example usage is in the punx codebase. This (new, yet-to-be-written) code would be run only on discretion during the release process.