Guidelines for project release notes
marnovo opened this issue · 2 comments
In some of our projects we don’t have release notes properly executed with a detailed changelog (preferably with links to issues), and sometimes no release notes at all, which is bad for internal and external users.
We should have general guidelines on the guide to standardize the content and process. E.g.:
- How frequently/what prompts a release?
- What should be provided in terms of files?
- What content should each release have and in what format?
How frequently/what prompts a release?
At maintainer's discrection. But in general, if a bug is fixed that is critical regression from latest release, a new release should be done ASAP. If, after some time, there are pending changes that are well tested, a release should be performed too.
What should be provided in terms of files?
For applications, our goal is to have Linux, macOS and Windows binaries posted to GitHub release page. Docker image pushed to Docker Hub if applicable.
What content should each release have and in what format?
An optional release description. If backwards incompatibility is introduced, it is encouraged to describe it. A list of changes with references to merged PRs, solved issues and author of the change should be added too.
go-git is probably one of our best examples: https://github.com/src-d/go-git/releases/tag/v4.2.0