From 89f58a4588b2865148de16c0a976a7cd71062ff7 Mon Sep 17 00:00:00 2001 From: Adi Seredinschi Date: Wed, 21 Oct 2020 17:27:57 +0200 Subject: [PATCH] Introduce unreleased section in changelog (#291) * New file and fixes for feature #274 * Updated contributing.md with changelog_pending discussion. * Link to contributing from main readme * Added release template * Removing changelog_pending * Updated the changelog --- .github/ISSUE_TEMPLATE/bug-report.md | 9 +++---- .github/ISSUE_TEMPLATE/feature-request.md | 5 ++++ .github/ISSUE_TEMPLATE/release-template.md | 20 +++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 9 +++---- CHANGELOG.md | 8 ++++++ CONTRIBUTING.md | 29 ++++++++++++++-------- README.md | 2 ++ 7 files changed, 61 insertions(+), 21 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/release-template.md diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 369cd676cb..6d627a6132 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -10,11 +10,9 @@ v Before smashing the submit button please review the template. v Please also ensure that this is not a duplicate issue :) ☺ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > --> - +## Crate + + ## Summary of Bug @@ -34,5 +32,6 @@ ____ - [ ] Not duplicate issue - [ ] Appropriate labels applied +- [ ] Appropriate milestone (priority) applied - [ ] Appropriate contributors tagged - [ ] Contributor assigned/self-assigned diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md index 555f14c1b1..871f07251d 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -11,6 +11,10 @@ v Word of caution: poorly thought-out proposals may be rejected v without deliberation ☺ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > --> +## Crate + + + ## Summary @@ -32,5 +36,6 @@ ____ - [ ] Not duplicate issue - [ ] Appropriate labels applied +- [ ] Appropriate milestone (priority) applied - [ ] Appropriate contributors tagged - [ ] Contributor assigned/self-assigned diff --git a/.github/ISSUE_TEMPLATE/release-template.md b/.github/ISSUE_TEMPLATE/release-template.md new file mode 100644 index 0000000000..bf70f7a681 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/release-template.md @@ -0,0 +1,20 @@ +--- +name: New Release Request +about: Create a proposal to track the release of a new version of IBC-RS +--- + + + + +# Release IBC-RS v.X.Y.Z + +⚡ + +- [ ] Create new release section in [CHANGELOG](./CHANGELOG.md) and move "unreleased" items into this section. +- [ ] Bump all crate versions to the new version. +- [ ] Reassign unfinished issues of previous milestone to the next milestone. \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d3873de643..27130aec4a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -17,9 +17,8 @@ ______ For contributor use: -- [ ] Unit tests written -- [ ] Added test to CI if applicable -- [ ] Updated CHANGELOG_PENDING.md +- [ ] Updated the __Unreleased__ section of [CHANGELOG.md](https://github.com/informalsystems/ibc-rs/blob/master/CHANGELOG.md) with the issue. +- [ ] If applicable: Unit tests written, added test to CI. - [ ] Linked to Github issue with discussion and accepted design OR link to spec that describes this work. -- [ ] Updated relevant documentation (`docs/`) and code comments -- [ ] Re-reviewed `Files changed` in the Github PR explorer +- [ ] Updated relevant documentation (`docs/`) and code comments. +- [ ] Re-reviewed `Files changed` in the Github PR explorer. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index cd915eb4bd..d54bae117e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## Unreleased Changes + +### FEATURES + +- Added "unreleased" section in `CHANGELOG.MD` to help streamline releases ([#274]). + +[#274]: https://github.com/informalsystems/ibc-rs/issues/274 + ## v0.0.4 *October 19, 2020* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6b67574a0..ed86363a57 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,16 +88,17 @@ To pull in updates from the origin repo, run ## Changelog -Every non-trivial PR must update the [CHANGELOG.md]. +Every non-trivial PR must update the [CHANGELOG.md](CHANGELOG.MD). The Changelog is *not* a record of what Pull Requests were merged; -the commit history already shows that. The Changelog is a notice to the user +the commit history already shows that. The Changelog is a notice to users about how their expectations of the software should be modified. It is part of the UX of a release and is a *critical* user facing integration point. The Changelog must be clean, inviting, and readable, with concise, meaningful entries. Entries must be semantically meaningful to users. If a change takes multiple Pull Requests to complete, it should likely have only a single entry in the -Changelog describing the net effect to the user. +Changelog describing the net effect to the user. Instead of linking PRs directly, we +instead prefer to log issues, which tend to be higher-level, hence more relevant for users. When writing Changelog entries, ensure they are targeting users of the software, not fellow developers. Developers have much more context and care about more @@ -110,26 +111,32 @@ and [Hashicorp Consul](http://github.com/hashicorp/consul/tree/master/CHANGELOG.md). See those changelogs for examples. -Changes for a given release should be split between the five sections: Security, Breaking +We currently split changes for a given release between these four sections: Breaking Changes, Features, Improvements, Bug Fixes. +Entries in the changelog should initially be logged in the __Unreleased__ section, which +represents a "staging area" for accumulating all the changes throughout a +release (see [Pull Requests](#pull-requests) below). With each release, +the entries then move from this section into their permanent place under a +specific release number in Changelog. + Changelog entries should be formatted as follows: ``` -- [pkg] \#xxx Some description about the change (@contributor) +- [pkg] Some description about the change ([#xxx]) (optional @contributor) ``` Here, `pkg` is the part of the code that changed (typically a -top-level crate, but could be /), `xxx` is the pull-request number, and `contributor` +top-level crate, but could be /), `xxx` is the issue number, and `contributor` is the author/s of the change. -It's also acceptable for `xxx` to refer to the relevent issue number, but pull-request +It's also acceptable for `xxx` to refer to the relevant pull request, but issue numbers are preferred. -Note this means pull-requests should be opened first so the changelog can then -be updated with the pull-request's number. +Note this means issues (or pull-requests) should be opened first so the changelog can then +be updated with the corresponding number. Changelog entries should be ordered alphabetically according to the -`pkg`, and numerically according to the pull-request number. +`pkg`, and numerically according to their issue/PR number. Changes with multiple classifications should be doubly included (eg. a bug fix that is also a breaking change should be recorded under both). @@ -152,7 +159,7 @@ PRs must: - make reference to an issue outlining the context. - update any relevant documentation and include tests. -- update the [changelog](#changelog) with a description of the change +- update [CHANGELOG.md](CHANGELOG.md) with a description of the change in the __Unreleased__ section. Pull requests should aim to be small and self contained to facilitate quick review and merging. Larger change sets should be broken up across multiple PRs. diff --git a/README.md b/README.md index fd9b2ec297..033a6b6f2c 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,8 @@ This repo contains the TLA+ specification and Rust implementation for the IBC modules and relayer. If you're interested in contributing, please comment on an issue or open a new one! +See also [CONTRIBUTING.MD](./CONTRIBUTING.md). + ## Versioning We follow [Semantic Versioning](https://semver.org/), but none of the APIs are stable yet. Expect