Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Guidelines for project release notes #219

Closed
marnovo opened this issue May 11, 2018 · 2 comments
Closed

Guidelines for project release notes #219

marnovo opened this issue May 11, 2018 · 2 comments
Assignees
@smola
Labels
enhancement

Comments

@marnovo
Copy link
Member

marnovo commented May 11, 2018 •
edited
Loading

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?
@marnovo
Copy link
Member Author

marnovo commented May 12, 2018

Also see:
https://github.com/src-d/feature-idea/issues/36#issuecomment-388535136
https://github.com/github-changelog-generator/github-changelog-generator#output-example

@smola
Copy link
Contributor

smola commented Jul 20, 2018

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

smola added a commit that referenced this issue Oct 17, 2018
@smola
engineering: add info about releases and release notes, fixes #219
4a9a302 
Signed-off-by: Santiago M. Mola <[email protected]>
@smola smola mentioned this issue Oct 17, 2018
Merged
@smola smola self-assigned this Oct 17, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@smola smola

Labels
enhancement
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@smola @marnovo