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.

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

Versioning, Change log and release instructions #1658

Merged
merged 11 commits into from
Jan 21, 2016
Merged

Versioning, Change log and release instructions #1658

merged 11 commits into from
Jan 21, 2016

Conversation

rap1ds
Copy link
Member

@rap1ds rap1ds commented Jan 20, 2016

This PR defines a set of practises for keeping versioning/changelog/upgrade notes up-to-date:

Todo

  • Add CHANGELOG.md. Follow the best-practices from keepchangelog.com
  • Add UPGRADE.md. This file contains upgrade notes
  • Add RELEASE.md. This file contains steps how to make a new release
  • Modify CONTRIBUTING.md: Add a new bullet about updating CHANGELOG
  • Upgrade README: Add links to the new files. Say explicitely that Sharetribe is using Semantic Versioning.

Review tip: Click here to see how these changes look in the Github UI

@rap1ds rap1ds force-pushed the versioning branch 2 times, most recently from 29df265 to 33293e4 Compare January 20, 2016 13:29
@rap1ds
Copy link
Member Author

rap1ds commented Jan 20, 2016

I'm still wondering one thing: I think we don't need to do a new release each time we merge a Pull Request. We can use common sense to gather a nice group of additions/fixes and then make a new release. Which may lead to a problem: If I want to make a new release to get my PATCH level change released, how do I know if there are unreleased MAJOR or MINOR level changes? Should we explicitly add that information to the CHANGELOG so that by reading the CHANGELOG you know what part of the version number to increase?

Here's an example:

CHANGELOG.md

## [Unreleased]

### Added
- MINOR Added support for payment gateway xyz [#99999](https://github.com/sharetribe/sharetribe/pull/99999)

### Fixes
- PATCH Fixes typos in README.md
- PATCH Fixed broken link in About page

By looking at this CHANGELOG it's obvious that the next version number needs to increase the MINOR version.

@bladealslayer
Copy link
Member

I think it would be nice if every PR comes with a corresponding entry in CHANGELOG.


All notable changes to this project will be documented in this file.

This project adheres to [Semantic Versioning](http://semver.org/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this isn't legally binding text, but should this be stated with a warning? Something like "This project adheres to Semantic Versioning where possible." etc. Otherwise we might have people being surprised when a minor version change breaks existing functionality. We cannot really account for all cases like a library with a public API.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's very true. I'll change this as you suggested.

@rap1ds
Copy link
Member Author

rap1ds commented Jan 21, 2016

@bladealslayer I totally agree. I added a note about that in the CONTRIBUTING.md https://github.com/sharetribe/sharetribe/pull/1658/files#diff-6a3371457528722a734f3c51d9238c13R15

rap1ds added a commit that referenced this pull request Jan 21, 2016
Versioning, Change log and release instructions
@rap1ds rap1ds merged commit fec8b1d into master Jan 21, 2016
@rap1ds rap1ds deleted the versioning branch January 21, 2016 09:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants