From b9d89887eb55e568820481519abceba2cdd19d84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Sun, 27 Aug 2017 02:55:42 +0300 Subject: [PATCH 01/15] RFC: Crate changelogs --- text/0000-crate-changelogs.md | 210 ++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 text/0000-crate-changelogs.md diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md new file mode 100644 index 00000000000..89d66eb0e9a --- /dev/null +++ b/text/0000-crate-changelogs.md @@ -0,0 +1,210 @@ +- Feature Name: crate-changelogs +- Start Date: 2017-08-27 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +Add changelog support to `cargo` and [crates.io](https://crates.io/). + +# Motivation +[motivation]: #motivation + +Citing [keepachangelog.com](http://keepachangelog.com): + +> What is a changelog? +> +> A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. +> +> Why keep a changelog? +> +> To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project. +> +> Who needs a changelog? +> +> People do. Whether consumers or developers, the end users of software are +> human beings who care about what's in the software. When the software changes, +> people want to know why and how. + +Encouraging crate authors to keep changelogs and increase its visibility for +crate users will definitely benefit crates ecosystem. + +This topic was brought several times, most notable notions are: + +- [Rustaceans: Please Keep a Changelog!](https://blog.dbrgn.ch/2015/12/1/rust-crates-keep-a-changelog/) ([reddit](https://www.reddit.com/r/rust/comments/3v1ndl/)) +- [Cargo issue](https://github.com/rust-lang/cargo/issues/2188) +- [Recent reddit thread](https://www.reddit.com/r/rust/comments/6vvhjh/) + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +Lets imagine you have a crate with three published versions (0.1.0, 0.1.1, 0.2.0) +and some yet unreleased changes. You can use `changelogs` folder in the root of +your crate to specify important changes in each crate version: +``` +├── Cargo.toml +├── changelogs +│ ├── header.md +│ ├── unreleased.md +│ ├── 0.1.0.md +│ ├── 0.1.1.md +│ └── 0.2.0.md +└── src + └── ... +``` + +All files except `header.md` and `unreleased.md` must be named as `.md`. + +`unreleased.md`, `0.1.0.md`, `0.1.1.md` and `0.2.0.md` should contain changes +in the format specified by [keepachangelog.com](http://keepachangelog.com), +i.e. written for humans (no commit history dumps) with changes grouped by +following types: + +- `Added` for new features. +- `Changed` for changes in existing functionality. +- `Deprecated` for soon-to-be removed features. +- `Removed` for now removed features. +- `Fixed` for any bug fixes. +- `Security` in case of vulnerabilities. + +For example: + +``` +# Added +- New functions: `foo`, `bar` +- Documentation for `Zoo` + +# Fixed +- Bugs: #1, #2, #3 +``` + +`unreleased.md` used for accumulation of features commited to the crate +repository, but not yet published. When publishing new crate version rename it +to the new crate version. If `cargo publish` will detect `changelogs` folder, +but not a changelog file for the new version it will refuse to publish it. +(this behaviour can be disabled by `--allow-no-changelog`) Although it will not +check changelogs for older versions. + +`header.md` is optional and can contain header to be included in the full +changelog which can be generated by `cargo changelog` command and which will +be displayed on [crates.io](https://crates.io/). For example it can have the +folowing content: +``` +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) +and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). + +``` + +By executing `cargo changelog` you can generate full changelog, by default +it will be saved as `CHANGELOG.md`, which will be formatted in the following +way: +``` +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) +and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). + +## [Unreleased] +### Added +- Function `bar` + +## [0.2.0] - 2017-03-03 +### Removed +- Deprecated function `foo` + +## [0.1.1] - 2017-02-02 +### Deprecated +- Function `foo` + +## [0.1.0] - 2017-01-01 +### Added +- Functions: `foo`, `bar` +- Documentation for `Zoo` + +### Fixed +- Bugs: #1, #2, #3 +``` + +Release dates will be taken from crates.io, additionally `[YANKED]` markers will +be added for yanked crate versions. Headers from changelog files will be +automatically converted to sub-headers. In case if changelog file will be +detected for unpublished version it will cause `cargo publish` and +`cargo changelog` to exit with an error. + +Alternatively you can use `CHANGELOG.md` maintained fully manually. If you +choose this approach you'll need to add `changelog` to `[package]` section of +your `Cargo.toml`, to enable its rendering on crates.io. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +Implementation of described features is fairly straightforward. Although it's +worth to mention several corner cases. + +## Crates or applications not published on crates.io + +Such projects can use manually maintained `CHANGELOG.md`. Alternatively we could +allow users to manually specify date in the changelog file, e.g.: +``` +2017-01-01 +# Added +- Functions: `foo`, `bar` +- Documentation for `Zoo` +``` + +This way `cargo changelog` will be able to generate full changelog without +crates.io. + +## Maintaining older crate versions + +Some crates will continue to publish updates for older versions. (e.g. +publishing bug fixes and feature updates for `1.0` branch with master on `2.0`) +For such cases it would be usefull to have a tool which will allow to pull +changelog files from other branches. + +One way to do it will be to add `cargo changelog pull` command which will +pull changelog files from crates.io. So for example we have `1.0.0.md` +and `2.0.0.md` on master branch, and we publish version `1.0.1` from branch +which contains `1.0.0.md` and `1.0.1.md`. Now we call `cargo changelog pull` on +master branch, this command will ask `crates.io` for changelog files which it +does not currently have, in our case it will be only `1.0.1.md`. + +In case of the conflict changelog files from bigger versions will be taken. +So if we have `1.0.1` and `1.0.2` with different `1.0.1.md` files, version from +`1.0.2` will be taken. Same goes for generation of full changelog on crates.io, +it should not only take latest published crate version, but also look for +missing changelog files in other crate versions if needed. + +# Drawbacks +[drawbacks]: #drawbacks + +- This proposal fixes MD as markup language for changelogs +- Splitting changelog into several files is unconventional and ties changelog +to crates.io registry + +# Rationale and Alternatives +[alternatives]: #alternatives + +Proposed way of handling changelogs reduces amount of manual work needed for +maintaining changelog and encourages crate authors to keep changelogs for all +versions through checks in `cargo publish`. Additionally it ensures full +synchronisation between crates.io registry and generated changelogs. + +Most obvious alternative would be to simply use `changelog` field in the +`[package]` section of `Cargo.toml`, similarly to `readme`, without splitting +changelog into several files. + +# Unresolved questions +[unresolved]: #unresolved-questions + +- Should we recommend to rgenerate `CHANGELOG.md` every time or link to crates.io +section instead? +- Support for non-english changelogs. What to do with [Unreleased] and +[YANKED]? +- Should we completely omit versions without changelog files in the full +changelog or should we add line with version and publishing date? From 0e7cb073d571809999a7cf4afd2c19c57a76bc9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Sun, 27 Aug 2017 03:22:10 +0300 Subject: [PATCH 02/15] Small elaboration --- text/0000-crate-changelogs.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index 89d66eb0e9a..0bf26f3956d 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -138,7 +138,9 @@ detected for unpublished version it will cause `cargo publish` and Alternatively you can use `CHANGELOG.md` maintained fully manually. If you choose this approach you'll need to add `changelog` to `[package]` section of -your `Cargo.toml`, to enable its rendering on crates.io. +your `Cargo.toml`, to enable its rendering on crates.io. In case if both +`changelogs` folder and `changelog` field are presented crates.io will use +changelog specified in the `changelog` field. # Reference-level explanation [reference-level-explanation]: #reference-level-explanation From a711dee76b58558506c4e2e94575e305020742c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Sun, 27 Aug 2017 03:33:32 +0300 Subject: [PATCH 03/15] Unresolved question: pre-release handling --- text/0000-crate-changelogs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index 0bf26f3956d..752438de08e 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -210,3 +210,4 @@ section instead? [YANKED]? - Should we completely omit versions without changelog files in the full changelog or should we add line with version and publishing date? +- How to handle pre-release versions? (e.g. `1.0.0-rc1`) From 35ca91ae90aba2dfa2989da41d9c24ccb28a0590 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Sun, 27 Aug 2017 14:01:14 +0300 Subject: [PATCH 04/15] Rewrite to a minimal version --- text/0000-crate-changelogs.md | 152 +++++++--------------------------- 1 file changed, 31 insertions(+), 121 deletions(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index 752438de08e..260878ef0a7 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -39,76 +39,28 @@ This topic was brought several times, most notable notions are: # Guide-level explanation [guide-level-explanation]: #guide-level-explanation -Lets imagine you have a crate with three published versions (0.1.0, 0.1.1, 0.2.0) -and some yet unreleased changes. You can use `changelogs` folder in the root of -your crate to specify important changes in each crate version: +To add changelog support to you crate just add `changelog` field to `[package]` +section of your `Cargo.toml` with the relative path to your changelog file: ``` -├── Cargo.toml -├── changelogs -│ ├── header.md -│ ├── unreleased.md -│ ├── 0.1.0.md -│ ├── 0.1.1.md -│ └── 0.2.0.md -└── src - └── ... +[package] +name = "foo" +version = "0.1.0" +changelog = "CHNAGELOG.md" ``` -All files except `header.md` and `unreleased.md` must be named as `.md`. +There is several requirements for changelogs: +- Must be written in MarkDown +- Must contain headers (#) or sub-headers (##) (in case if file starts with +the header) which start from crate version (`0.1.1` or `[0.1.1]`), except the +first (sub)-header which can contains "Unreleased" changes -`unreleased.md`, `0.1.0.md`, `0.1.1.md` and `0.2.0.md` should contain changes -in the format specified by [keepachangelog.com](http://keepachangelog.com), -i.e. written for humans (no commit history dumps) with changes grouped by -following types: - -- `Added` for new features. -- `Changed` for changes in existing functionality. -- `Deprecated` for soon-to-be removed features. -- `Removed` for now removed features. -- `Fixed` for any bug fixes. -- `Security` in case of vulnerabilities. - -For example: - -``` -# Added -- New functions: `foo`, `bar` -- Documentation for `Zoo` - -# Fixed -- Bugs: #1, #2, #3 -``` - -`unreleased.md` used for accumulation of features commited to the crate -repository, but not yet published. When publishing new crate version rename it -to the new crate version. If `cargo publish` will detect `changelogs` folder, -but not a changelog file for the new version it will refuse to publish it. -(this behaviour can be disabled by `--allow-no-changelog`) Although it will not -check changelogs for older versions. - -`header.md` is optional and can contain header to be included in the full -changelog which can be generated by `cargo changelog` command and which will -be displayed on [crates.io](https://crates.io/). For example it can have the -folowing content: +The good example to follow can be a format described by [keepachangelog.com](http://keepachangelog.com): ``` # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). - -``` - -By executing `cargo changelog` you can generate full changelog, by default -it will be saved as `CHANGELOG.md`, which will be formatted in the following -way: -``` -# Changelog -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) -and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). - ## [Unreleased] ### Added - Function `bar` @@ -130,84 +82,42 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Bugs: #1, #2, #3 ``` -Release dates will be taken from crates.io, additionally `[YANKED]` markers will -be added for yanked crate versions. Headers from changelog files will be -automatically converted to sub-headers. In case if changelog file will be -detected for unpublished version it will cause `cargo publish` and -`cargo changelog` to exit with an error. +Although it's recommended to write changelogs by hand, you can use other +tools such as [`clog`](https://crates.io/crates/clog) to generate it based on +the structured commit history. -Alternatively you can use `CHANGELOG.md` maintained fully manually. If you -choose this approach you'll need to add `changelog` to `[package]` section of -your `Cargo.toml`, to enable its rendering on crates.io. In case if both -`changelogs` folder and `changelog` field are presented crates.io will use -changelog specified in the `changelog` field. +If `changelog` field is specified in the `Cargo.toml`, `cargo publish` will +check if changelog contains section for the new version and producing error if +it will not be found. This behaviour can be disabled with `--allow-no-changelog` +option. Also crates.io will refuse to accept crates if changelog file does not +follow rules stated earlier. # Reference-level explanation [reference-level-explanation]: #reference-level-explanation -Implementation of described features is fairly straightforward. Although it's -worth to mention several corner cases. - -## Crates or applications not published on crates.io - -Such projects can use manually maintained `CHANGELOG.md`. Alternatively we could -allow users to manually specify date in the changelog file, e.g.: -``` -2017-01-01 -# Added -- Functions: `foo`, `bar` -- Documentation for `Zoo` -``` - -This way `cargo changelog` will be able to generate full changelog without -crates.io. - -## Maintaining older crate versions - -Some crates will continue to publish updates for older versions. (e.g. -publishing bug fixes and feature updates for `1.0` branch with master on `2.0`) -For such cases it would be usefull to have a tool which will allow to pull -changelog files from other branches. - -One way to do it will be to add `cargo changelog pull` command which will -pull changelog files from crates.io. So for example we have `1.0.0.md` -and `2.0.0.md` on master branch, and we publish version `1.0.1` from branch -which contains `1.0.0.md` and `1.0.1.md`. Now we call `cargo changelog pull` on -master branch, this command will ask `crates.io` for changelog files which it -does not currently have, in our case it will be only `1.0.1.md`. +Implementation of described features is fairly straightforward. -In case of the conflict changelog files from bigger versions will be taken. -So if we have `1.0.1` and `1.0.2` with different `1.0.1.md` files, version from -`1.0.2` will be taken. Same goes for generation of full changelog on crates.io, -it should not only take latest published crate version, but also look for -missing changelog files in other crate versions if needed. +Rendering on crates.io can be done through additional link on top bar: +![1](https://user-images.githubusercontent.com/329626/29746037-86920e8a-8ad5-11e7-828c-4d32f6ac4cf2.png) # Drawbacks [drawbacks]: #drawbacks - This proposal fixes MD as markup language for changelogs -- Splitting changelog into several files is unconventional and ties changelog -to crates.io registry +- It does not define convention for changelogs, just some bare-bone rules. Which +will result in different changelog formats used across ecosystem, thus hindering +machine readability of changelogs and will make it harder to build tools based +on this proposal. # Rationale and Alternatives [alternatives]: #alternatives -Proposed way of handling changelogs reduces amount of manual work needed for -maintaining changelog and encourages crate authors to keep changelogs for all -versions through checks in `cargo publish`. Additionally it ensures full -synchronisation between crates.io registry and generated changelogs. +This proposal defines minimal format for changelog, leaving as much flexibilty +for crate authors as possible withoout droping the basic machine readability. -Most obvious alternative would be to simply use `changelog` field in the -`[package]` section of `Cargo.toml`, similarly to `readme`, without splitting -changelog into several files. +Alternative would be to specify stricter conventions around changelog content. # Unresolved questions [unresolved]: #unresolved-questions -- Should we recommend to rgenerate `CHANGELOG.md` every time or link to crates.io -section instead? -- Support for non-english changelogs. What to do with [Unreleased] and -[YANKED]? -- Should we completely omit versions without changelog files in the full -changelog or should we add line with version and publishing date? -- How to handle pre-release versions? (e.g. `1.0.0-rc1`) +- Should we add a badge for changelog? From 4ac26757016a1069f00f3b965e36e21c81f1d2be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Sun, 27 Aug 2017 14:31:47 +0300 Subject: [PATCH 05/15] Typo fix, small clarification --- text/0000-crate-changelogs.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index 260878ef0a7..24c4ffa1ba9 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -52,7 +52,10 @@ There is several requirements for changelogs: - Must be written in MarkDown - Must contain headers (#) or sub-headers (##) (in case if file starts with the header) which start from crate version (`0.1.1` or `[0.1.1]`), except the -first (sub)-header which can contains "Unreleased" changes +first (sub)-header which can contain "Unreleased" changes + +Everything in the section defined by (sub)-header will be treated as changes +which were made in the specified version. The good example to follow can be a format described by [keepachangelog.com](http://keepachangelog.com): ``` @@ -113,7 +116,7 @@ on this proposal. [alternatives]: #alternatives This proposal defines minimal format for changelog, leaving as much flexibilty -for crate authors as possible withoout droping the basic machine readability. +for crate authors as possible without dropping the basic machine readability. Alternative would be to specify stricter conventions around changelog content. From 828fe4086f224fc14e6accefae3e79df995bf47a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Sun, 27 Aug 2017 16:41:47 +0300 Subject: [PATCH 06/15] Added external links alternative --- text/0000-crate-changelogs.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index 24c4ffa1ba9..9472a434518 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -120,6 +120,9 @@ for crate authors as possible without dropping the basic machine readability. Alternative would be to specify stricter conventions around changelog content. +Another alternative would be to use link to external resource in the `changelog` +field instead of path to the readme file. + # Unresolved questions [unresolved]: #unresolved-questions From 53063e39f4b32de0fca0cdb48a9c7bf3846f96ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Mon, 28 Aug 2017 00:54:01 +0300 Subject: [PATCH 07/15] Updated changelog requirements --- text/0000-crate-changelogs.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index 9472a434518..e9e9b01a98e 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -48,16 +48,25 @@ version = "0.1.0" changelog = "CHNAGELOG.md" ``` -There is several requirements for changelogs: -- Must be written in MarkDown -- Must contain headers (#) or sub-headers (##) (in case if file starts with -the header) which start from crate version (`0.1.1` or `[0.1.1]`), except the -first (sub)-header which can contain "Unreleased" changes - -Everything in the section defined by (sub)-header will be treated as changes -which were made in the specified version. - -The good example to follow can be a format described by [keepachangelog.com](http://keepachangelog.com): +There is several requirements for changelogs, in case if one of them is not +upheld, crates.io will refuse to accept such crate: +- Must be written in MarkDown (but number of supported markup languages can be +extended in future) +- Must contain headlines (#) or sub-headlines (##) (in case if changelog starts +with the headline) which start with crate version (`0.1.1` or `[0.1.1]`) +- As a consequence of the last requirement changelog must not contain +"Unreleased" section +- All crate versions listed in the changelog must have been published +earlier on crates.io, except the first entry, version in which could be equal +to `version` field in `Cargo.toml` (i.e. first entry is for version which going +to be published) + +This requirements are enforced only by `cargo publish`.Everything in the section +defined by (sub)-headline will be treated as changes which were made in the +specified version. + +The good example to follow can be a format described by +[keepachangelog.com](http://keepachangelog.com): ``` # Changelog All notable changes to this project will be documented in this file. @@ -89,6 +98,9 @@ Although it's recommended to write changelogs by hand, you can use other tools such as [`clog`](https://crates.io/crates/clog) to generate it based on the structured commit history. +Additionally you can include migration notes, which will help crate users to +upgrade to the new version. + If `changelog` field is specified in the `Cargo.toml`, `cargo publish` will check if changelog contains section for the new version and producing error if it will not be found. This behaviour can be disabled with `--allow-no-changelog` From 4b40323406d5bfb4353a7a4ed5a7af072d6ff268 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Mon, 28 Aug 2017 00:58:23 +0300 Subject: [PATCH 08/15] Removed unreleased section --- text/0000-crate-changelogs.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index e9e9b01a98e..9b5c14f5f5b 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -73,9 +73,6 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). -## [Unreleased] -### Added -- Function `bar` ## [0.2.0] - 2017-03-03 ### Removed From f44486e31739f3d11bb9334022a3584a82a013d3 Mon Sep 17 00:00:00 2001 From: newpavlov Date: Thu, 31 Aug 2017 12:49:27 +0300 Subject: [PATCH 09/15] Enabled links to external resources, plus minor changes --- text/0000-crate-changelogs.md | 142 +++++++++++++++++++++++++++------- 1 file changed, 115 insertions(+), 27 deletions(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index 9b5c14f5f5b..eeed9eb80bb 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -14,18 +14,18 @@ Add changelog support to `cargo` and [crates.io](https://crates.io/). Citing [keepachangelog.com](http://keepachangelog.com): > What is a changelog? -> +> > A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project. > -> Why keep a changelog? +> Why keep a changelog? > > To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project. > -> Who needs a changelog? +> Who needs a changelog? > > People do. Whether consumers or developers, the end users of software are > human beings who care about what's in the software. When the software changes, -> people want to know why and how. +> people want to know why and how. Encouraging crate authors to keep changelogs and increase its visibility for crate users will definitely benefit crates ecosystem. @@ -39,35 +39,40 @@ This topic was brought several times, most notable notions are: # Guide-level explanation [guide-level-explanation]: #guide-level-explanation -To add changelog support to you crate just add `changelog` field to `[package]` -section of your `Cargo.toml` with the relative path to your changelog file: -``` +There is two ways to add changelog support to your crate: providing changelog +file explicitly or linking to an external resource. + +## Explicit changelog file + +Add `changelog` field to `[package]` section of your `Cargo.toml` with the +relative path to your changelog file: +```toml [package] name = "foo" version = "0.1.0" changelog = "CHNAGELOG.md" ``` -There is several requirements for changelogs, in case if one of them is not +There is several requirements for changelog files, in case if one of them is not upheld, crates.io will refuse to accept such crate: -- Must be written in MarkDown (but number of supported markup languages can be +- Must be written in MarkDown (number of supported markup languages can be extended in future) -- Must contain headlines (#) or sub-headlines (##) (in case if changelog starts -with the headline) which start with crate version (`0.1.1` or `[0.1.1]`) +- Must contain headlines or sub-headlines (in case if changelog starts with the +headline) which start with crate version (`0.1.1` or `[0.1.1]`) - As a consequence of the last requirement changelog must not contain "Unreleased" section - All crate versions listed in the changelog must have been published -earlier on crates.io, except the first entry, version in which could be equal +earlier on crates.io, except the first entry, version for which can be equal to `version` field in `Cargo.toml` (i.e. first entry is for version which going -to be published) +to be published). -This requirements are enforced only by `cargo publish`.Everything in the section -defined by (sub)-headline will be treated as changes which were made in the -specified version. +This requirements are enforced only by `cargo publish` and subsequently +by crates.io. Everything in the sections defined by (sub)-headlines will be +treated as changes which were made in the respective versions. The good example to follow can be a format described by [keepachangelog.com](http://keepachangelog.com): -``` +```markdown # Changelog All notable changes to this project will be documented in this file. @@ -99,10 +104,74 @@ Additionally you can include migration notes, which will help crate users to upgrade to the new version. If `changelog` field is specified in the `Cargo.toml`, `cargo publish` will -check if changelog contains section for the new version and producing error if -it will not be found. This behaviour can be disabled with `--allow-no-changelog` -option. Also crates.io will refuse to accept crates if changelog file does not -follow rules stated earlier. +check if changelog contains section for the new version producing error +otherwise. This behaviour can be disabled with `--allow-no-changelog` +option. But it will not disable other changelog checks. + +### Additionall changelog examples + +```markdown +# Anything goes here + +Anything goes here. + +## 1.2.3 + +Anything goes here. + +### Anything goes here. + +It's still part of the changes made in 1.2.3 + +#### And this too + +Anything goes here. + +## 0.2.3 + +Anything goes here. +``` + +```markdown +# 1.2.3 + +Anything goes here. + +# 0.2.3 + +Anything goes here. + +# 0.0.3 + +Anything goes here. +``` + +```markdown +1.2.3 +===== + +Anything goes here. + +1.0.0-rc1 +===== + +Anything goes here. + +``` + +## Link to an externall resource + +Alternatively you can link to a changelog published on external resource. If +`changelog` field will start with `http:` or `https:` it will be treated as an +URL. + +```toml +[package] +name = "foo" +version = "0.1.0" +changelog = "https://github.com/foo/bar/releases" +``` + # Reference-level explanation [reference-level-explanation]: #reference-level-explanation @@ -112,14 +181,34 @@ Implementation of described features is fairly straightforward. Rendering on crates.io can be done through additional link on top bar: ![1](https://user-images.githubusercontent.com/329626/29746037-86920e8a-8ad5-11e7-828c-4d32f6ac4cf2.png) +It will lead either to changelog section on crates.io with the rendered +changelog (for explicilty provided changelog file) or to external resource +provided in the `changelog` field. + +# Future extensions +[feature-extensions]: #feature-extensions + +It will be possible to define additional extensions which will use different +prefixes from `http` and `https` in the `changelog` field. +Such extension(s) can be used for example for handling stricter machine readable +changelog formats which will be generated by externall tools like +[`clog`](https://crates.io/crates/clog) or other different approaches to +changelogs. + +`changelog` field with such extensions can look like `foo:bar`, where `foo` is +format prefix and `bar` for example external `cargo` tool which will be executed +by `cargo publish` and which should produce result specified by `foo` prefix. + # Drawbacks [drawbacks]: #drawbacks -- This proposal fixes MD as markup language for changelogs +- This proposal fixes MarkDown as markup language for changelogs - It does not define convention for changelogs, just some bare-bone rules. Which will result in different changelog formats used across ecosystem, thus hindering machine readability of changelogs and will make it harder to build tools based on this proposal. +- Some people consider proposed requirements for changelog files unnecessary and +overly strict. # Rationale and Alternatives [alternatives]: #alternatives @@ -127,12 +216,11 @@ on this proposal. This proposal defines minimal format for changelog, leaving as much flexibilty for crate authors as possible without dropping the basic machine readability. -Alternative would be to specify stricter conventions around changelog content. - -Another alternative would be to use link to external resource in the `changelog` -field instead of path to the readme file. +Alternative would be to specify stricter or more relaxed conventions around +changelog content. # Unresolved questions [unresolved]: #unresolved-questions -- Should we add a badge for changelog? +- Should we check correctness and/or availability of URL in the `changelog` +field? From 3f0d80a5a0a6b1dc7d040e51c16b2766f4cf5bfb Mon Sep 17 00:00:00 2001 From: newpavlov Date: Thu, 31 Aug 2017 12:50:42 +0300 Subject: [PATCH 10/15] Small fix --- text/0000-crate-changelogs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index eeed9eb80bb..f53766eae1e 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -153,7 +153,7 @@ Anything goes here. Anything goes here. 1.0.0-rc1 -===== +========= Anything goes here. From 4676beb9c2ef191366b0715a68c9c6700b0b3539 Mon Sep 17 00:00:00 2001 From: newpavlov Date: Thu, 31 Aug 2017 12:53:48 +0300 Subject: [PATCH 11/15] Small clarification --- text/0000-crate-changelogs.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index f53766eae1e..d3327d64ed0 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -172,6 +172,8 @@ version = "0.1.0" changelog = "https://github.com/foo/bar/releases" ``` +None of the rules described in the previous section will apply to changelogs +provided this way, even if they link to markdown files directly. # Reference-level explanation [reference-level-explanation]: #reference-level-explanation From b2ad4ba309d3e899a415e65a2577554e79c410ca Mon Sep 17 00:00:00 2001 From: newpavlov Date: Thu, 31 Aug 2017 14:13:46 +0300 Subject: [PATCH 12/15] Added unresolved question regarding unreleased section --- text/0000-crate-changelogs.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index d3327d64ed0..bd569967f97 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -226,3 +226,5 @@ changelog content. - Should we check correctness and/or availability of URL in the `changelog` field? +- Should we allow empty "unreleased" section in the changelog, so authors +will not delete and recreate it every time a release is made. From e7c50d45a803e772b5d07e57df693fc86827a85d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Mon, 18 Sep 2017 04:38:55 +0300 Subject: [PATCH 13/15] Updated rules, fixed typos --- text/0000-crate-changelogs.md | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index bd569967f97..a43e104d853 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -53,21 +53,24 @@ version = "0.1.0" changelog = "CHNAGELOG.md" ``` -There is several requirements for changelog files, in case if one of them is not -upheld, crates.io will refuse to accept such crate: +There is several requirements for changelogs, in case if one of them is not +upheld, `cargo publish` and crates.io will refuse to accept such crate: - Must be written in MarkDown (number of supported markup languages can be extended in future) -- Must contain headlines or sub-headlines (in case if changelog starts with the -headline) which start with crate version (`0.1.1` or `[0.1.1]`) +- Must contain headlines (#) or sub-headlines (##) (in the case if changelog +starts with the headline) which start with the correct semantic version, +possibly inside square brackets (`0.1.1` or `[0.1.1]`) - As a consequence of the last requirement changelog must not contain "Unreleased" section -- All crate versions listed in the changelog must have been published -earlier on crates.io, except the first entry, version for which can be equal -to `version` field in `Cargo.toml` (i.e. first entry is for version which going -to be published). +- Optional: Version of first section defined by (sub)-headline should be equal +to the `version` field in the `Cargo.toml` -This requirements are enforced only by `cargo publish` and subsequently -by crates.io. Everything in the sections defined by (sub)-headlines will be +Last requirement is enabled by default, but can be disabled by executing +`cargo publish --allow-no-changelog`. This is the safeguard in case if crate +author will forget to update changelog for the version which getting +published. + +Everything in the sections defined by (sub)-headlines will be treated as changes which were made in the respective versions. The good example to follow can be a format described by @@ -108,7 +111,7 @@ check if changelog contains section for the new version producing error otherwise. This behaviour can be disabled with `--allow-no-changelog` option. But it will not disable other changelog checks. -### Additionall changelog examples +### Additional changelog examples ```markdown # Anything goes here @@ -147,7 +150,7 @@ Anything goes here. ``` ```markdown -1.2.3 +1.0.0 ===== Anything goes here. @@ -159,7 +162,7 @@ Anything goes here. ``` -## Link to an externall resource +## Link to an external resource Alternatively you can link to a changelog published on external resource. If `changelog` field will start with `http:` or `https:` it will be treated as an @@ -193,7 +196,7 @@ provided in the `changelog` field. It will be possible to define additional extensions which will use different prefixes from `http` and `https` in the `changelog` field. Such extension(s) can be used for example for handling stricter machine readable -changelog formats which will be generated by externall tools like +changelog formats which will be generated by external tools like [`clog`](https://crates.io/crates/clog) or other different approaches to changelogs. @@ -204,7 +207,8 @@ by `cargo publish` and which should produce result specified by `foo` prefix. # Drawbacks [drawbacks]: #drawbacks -- This proposal fixes MarkDown as markup language for changelogs +- This proposal fixes MarkDown as markup language for changelogs (although +number of supported markup languages can be extended in future) - It does not define convention for changelogs, just some bare-bone rules. Which will result in different changelog formats used across ecosystem, thus hindering machine readability of changelogs and will make it harder to build tools based From f1919f8e09b5c2dfe7715e24dde16c6f959489c1 Mon Sep 17 00:00:00 2001 From: newpavlov Date: Mon, 18 Sep 2017 12:05:15 +0300 Subject: [PATCH 14/15] Added URL availability check --- text/0000-crate-changelogs.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index a43e104d853..dfab15a4d91 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -178,6 +178,11 @@ changelog = "https://github.com/foo/bar/releases" None of the rules described in the previous section will apply to changelogs provided this way, even if they link to markdown files directly. +Before publishing crate `cargo publish` will attempt to check if provided URL is +reachable (e.g by checking if returned status code is equal to 200 or 30x), +returning error if not. This behaviour can be disabled by +`--allow-no-changelog` option. + # Reference-level explanation [reference-level-explanation]: #reference-level-explanation @@ -228,7 +233,5 @@ changelog content. # Unresolved questions [unresolved]: #unresolved-questions -- Should we check correctness and/or availability of URL in the `changelog` -field? - Should we allow empty "unreleased" section in the changelog, so authors will not delete and recreate it every time a release is made. From ac0a06b48cc6e5ac899e7879d1ffa19c89b9b30a Mon Sep 17 00:00:00 2001 From: Artyom Pavlov Date: Thu, 6 Sep 2018 22:18:00 +0300 Subject: [PATCH 15/15] fix typo --- text/0000-crate-changelogs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-crate-changelogs.md b/text/0000-crate-changelogs.md index dfab15a4d91..1cb13a32ccb 100644 --- a/text/0000-crate-changelogs.md +++ b/text/0000-crate-changelogs.md @@ -50,7 +50,7 @@ relative path to your changelog file: [package] name = "foo" version = "0.1.0" -changelog = "CHNAGELOG.md" +changelog = "CHANGELOG.md" ``` There is several requirements for changelogs, in case if one of them is not