CHANGELOG.md Homogeneity Project

[mxygem]

Project

Normalize all CHANGELOG/history files across all necessary cucumber repos. Please follow the guidelines below and if you have any questions, please ask!

Guidelines

• Naming: Files must be named CHANGELOG.md. If they are anything else, please rename them to fit.
• Line entry format: [Module] Message ([Issue Link], [Issue Link] Contributor Name One, Contributor Name Two) (Link to user's github if available) See the Gherkin CHANGELOG for an example.
• Entries should be grouped into one of the following: Removed, Added, Changed, Fixed. Please prefix with an H3 tag. Aka ###
• Existing entries in files do not need to be completely updated, but please make sure that mentions to issues/pull requests such as (PR #123) are updated to be point to an appropriate Github URL.
  • Example: (#123) would turn into [#123](https://github.com/cucumber/cucumber/pull/123] or #123
  • Don't worry about being correct with pull/issue as they will redirect to one another as needed.
  • I've created a tool to automatically handle this for you.
  • Please use the template below for new files or for existing files, make sure that it includes the data below:

# CHANGE LOG

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

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

This document is formatted according to the principles of [Keep A CHANGELOG](http://keepachangelog.com).

Please visit [cucumber/CONTRIBUTING.md](https://github.com/cucumber/cucumber/blob/master/CONTRIBUTING.md) for more info on how to contribute to Cucumber.

----

## [Unreleased] - In Git

### Removed

### Added

* Added this CHANGELOG.md file per [cucumber/cucumber #251](https://github.com/cucumber/cucumber/issues/251)

### Changed

### Fixed

<!-- Releases -->

<!-- Contributors -->
[username]:        https://github.com/username

List of Repos By Current Tracking Type

All below need to be updated/checked. Please edit the list yourself or let me know when you've completed a repo and I will update the list here.
(double ~~ on both sides)

Changelog.md

• cucumber-js

History.md

• aruba
• cucumber-cpp
• cucumber-jvm
• cucumber-rails
• cucumber-ruby
• cucumber-ruby-core
• multi_test

No history tracking file

• aruba-contrib
• aruba-website
• commitbit
• cucumber-eclipse
• cucumber-electron
• cucumber-html
• cucumber-jvm-deps
• cucumber-lua
• cucumber-react
• cucumber-ruby-tcl
• cucumber-ruby-wire
• cucumber-tcl-wire
• github-issue-stats

---

---

Historical data moving out of the main section

Summary

I've wanted to get various informational documents consistent across our repos as there are pretty significant differences between them. Normalization will help messaging be consistent across the board allowing different users to be able to read all history files across Cucumber regardless of which language specific repo of which they're most familiar.

Current Implementations

Examples:

• cucumber-ruby uses an update-history script to manage their HISTORY.md file
• cucumber-js doesn't have a specific format to use for CHANGELOG.md but suggests using a specific git log.

Possible Solution

Aslak suggested Keep a Changelog for our history files. This uses a clear format and groups things by type, similar to what we're doing today.

Questions/Tuning

1. Naming: Should we use History.md or CHANGELOG.md across repos?
   1a. Should what we decide on be in all caps?
2. Every repo (imo) should have some sort of history tracking file so we'll need to go through and add them to repos that don't currently have them.
   2a. Should we create a day forward file or try to wrangle past commit history into the files we create?
3. Should we change our change 'types' to match KaC's guidance or continue to use our own?
4. KaC does not include a method for including issue numbers, shall we just continue with including them as links at the end with the text being just the issue number?
5. There are a lot of repos below that are listed as read-only, are mirrors, or are just stale overall. Should we be adding tracking files to these ones as well?
6. Guidance: We should include a link at the top of each tracking file pointing to the master contributing file.
7. Guidance: Similar to the Ruby repo, I would like each repo to have a local script that contributors run to update the tracking file with the issue tag. This way we can help keep formatting similar across repos and also enforce a 'newest first' ordering of issues. (Going to make this into its own Issue)

[aslakhellesoy]

Great research @jaysonesmith. Some of the repos without a changelog file are read-only mirrors of the cucumber/cucumber monorepo:

• gherkin-c
• gherkin-dotnet
• gherkin-go
• gherkin-java
• gherkin-javascript
• gherkin-jvm-deps
• gherkin-lint-javascript
• gherkin-objective-c
• cucumber-expressions-java
• cucumber-expressions-javascript
• cucumber-expressions-ruby
• tag-expressions-java
• tag-expressions-javascript
• tag-expressions-ruby

These repos should not have a changelog - their changelog is in monorepo:

• https://github.com/cucumber/cucumber/blob/master/gherkin/CHANGELOG.md
• https://github.com/cucumber/cucumber/blob/master/cucumber-expressions/CHANGELOG.md
• https://github.com/cucumber/cucumber/blob/master/tag-expressions/CHANGELOG.md

Some repos don't get tagged and released - they're just "ongoing":

• cucumber (monorepo) - there are many changelogs here, just not at the root
• cucumber-java-skeleton
• aruba-getting-started
• website
• docs.cucumber.io

Some I just moved to the attic:

• cucumber-pretty-formatter
• gherkin
• cucumber-ruby-http

And this one got deleted:

• cucumber-ruby-dev

So I think the remaining ones need a changelog.

Now your questions:

1. Although most projects use History.md, I'd be happy to adopt CHANGELOG.md as the standard filename. All caps fits well with README.md and CONTRIBUTING.md.
2. Let's not worry about the past - new CHANGELOG.md files should only list what's happened after the file was added.
3. I think we should use a consistent style across all repos. I think the following info is important (see cucumber-expressions and gherkin for examples:
   • Change categories (New features, Added, Removed etc)
   • Links to issues/PRs
   • Attributions (links to contributors)
   • Links to a full diff between releases
   • Release date
     Each entry is added manually, and it's a little bit tedious, but not too bad IMO. Maybe we can create a small bash script that adds a line with a simple command line.
4. See examples in 3
5. Explained above
6. Agree! The file is there - just needs updating with the process discussed recently on the mailing list.
7. Duplicated scripts are hard to maintain. I suggest adding a bash function to scripts/functions.sh in the monorepo

[mxygem]

Thanks for the feedback @aslakhellesoy that is all incredibly useful info!

[mpkorstanje]

1. Naming: Should we use History.md or CHANGELOG.md across repos?
   1a. Should what we decide on be in all caps?

Looking at CONTRIBUTING.md, LICENSE, README.md and TODO.md I reckon CHANGELOG.md should be the preferred naming. The capitals appear to indicate these are documentation.

KaC does not include a method for including issue numbers, shall we just continue with including them as links at the end with the text being just the issue number?

I'm happy with the [Module] Message ([Issue Link], [Issue Link] Contributor Name One, Contributor Name Two) format.

I have no strong preference on the other items.

[mxygem]

@aslakhellesoy I've trimmed the repo list with your guidance in mind. Could you take another look at it to make sure we're still not including anything unnecessarily?

Looking at CONTRIBUTING.md, LICENSE, README.md and TODO.md I reckon CHANGELOG.md should be the preferred naming. The capitals appear to indicate these are documentation.

Works for me! Thanks for getting on board with this so quickly!

I'm happy with the [Module] Message ([Issue Link], [Issue Link] Contributor Name One, Contributor Name Two) format.

We can certainly look to go this way. The Ruby repo doesn't currently follow this convention, but it should be able to.

[mlvandijk]

Ad 3/4: Wouldn't it be helpful to include one of the keywords to automatically close the related issue? https://help.github.com/articles/closing-issues-using-keywords/

[mxygem]

@mlvandijk This wouldn't be touching the Issue/PR directly, only the changelog file so I'm not should (and I could be wrong) that would work?

[mxygem]

I wrote a simple ruby script for automatically looking for issue numbers like [#123] and adds a full Github url. Save to a file and specify the repo you want it to insert at run time.

To run: ruby updater.rb [repo-name] [CHANGELOG.md]

output = ''
File.foreach(ARGV[1]) do |line|
  match = line.match(/\[#(\d{1,3})\]/)
  output += match ? line.gsub(/\[#\d{1,3}\]/, "#{match}(https://github.com/cucumber/#{ARGV[0]}/issues/#{match[1]})") : line
end
File.open("#{ARGV[1]}", "w") {|file| file.puts output }

[brasmusson]

Keep a Changelog says that Changelog is "a curated, chronologically ordered list". By their own example it also says the "curated" trumps "chronologically ordered". Using git blame on their own Changelog reviles that in

- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from @tianshuo. 	
- German translation from @mpbzh & @Art4.
- Italian translation from @azkidenz.
- Swedish translation from @magol.

the entries on German and Italian translations was added two months after the entry on new guiding principles. When reading the Changelog to find out what changes were made in a release, I can see that is makes sense to list all added translations together. My take on this is that scrips are handy, but it is still the person using the script to update the Changelog that is responsible that the result is appropriate.

As an example from one of our own project, I think that all "Fix Metrics/LineLength" PR:s (cucumber/cucumber-ruby#1174, cucumber/cucumber-ruby#1175, cucumber/cucumber-ruby#1176 - of which the first is not mentioned in the changelog at all), should rather be grouped into one entry:

* Fix Lint/DuplicateMethods (#1174, #1175, #1176 ...)

now they seems to take up an unnecessary amount of real estate in the changelog.

[brasmusson]

This wouldn't be touching the Issue/PR directly, only the changelog

@jaysonesmith @mlvandijk It would be great is the script could detect and add the issues closed by the pull request (which "can" be done by parsing the pull request description), otherwise (at least me that thinks that this information belongs in the changelog) that information needs to be manually added after the script has been executed.

In either case their is still the work of checking (and if necessary adding) that the pull request description closes the appropriate issues, before merging the pull request.

[mlvandijk]

@js, for cucumber-jvm, I put: "Please see CONTRIBUTING.md on how to contribute to Cucumber." - Let me know if that's ok and it (#1204) can be merged :) Also, that could (should) then be the same across repos?

[mxygem]

@mlvandijk That works for me. I've put the same at the top of the file for Aruba.

[mlvandijk]

@js You're right, Github won't auto-close from the CHANGELOG. Would it be good practice to include these keywords in commit messages? Or would we prefer to close issues manually?
@brasmusson I was thinking the "Message" part in the line entry format would be the commit message, although I also very much agree with the need for it to be "curated" as the whole point of the changelog is to provide information on notable changes in a way that is easily understandable. It shouldn't be just a chronological list of commits (you can get those from git). Therefore, sometimes it might also be useful to expand on the basic info provided in the line entry format, i.e. in case of breaking changes / wider implications of the change(?)

[brasmusson]

Would it be good practice to include these keywords in commit messages? Or would we prefer to close issues manually?

@mlvandijk I prefer to close issues with pull request descriptions. Yes, in case I would push a fix for an issue directly to master, then that commit would both fix the issue and update the changelog, and its commit message would close the issue. I would not close issues (using those keywords in the commit message) with commits pushed to pull request branches. In that case I think that closing the issues is for the pull request description to do (using those keywords). Closing issues manually is just extra manual work which is to easily to be forgotten, and you will anyway when closing the issue refer to the pull request or commit that did the fix to get that traceability on Github, so it is much better to let Github to create that traceability automatically.

[mxygem]

Got a bunch of the new changelogs done and this issue is almost done, at least initially. (I didn't merge any this time! ;) )

[mxygem]

Disregarding my mention of this issue in the above 1194, could I get a review of the open PRs above, please? Just waiting for approval, basically. Thanks!

[mlvandijk]

PRs look fine to me as far as the text & links, but I'm not a contributor on these projects so

1. cannot verify the contributors are correct/complete
2. do not want to take the liberty to merge
3. not all of the checks have completed / passed (updated):

• CHANGELOG add for cucumber/cucumber #251 react-components#1
  All checks have failed
• Update CHANGELOG.md cucumber-ruby#1194
  Some checks were not successful
• CHANGELOG add for cucumber/cucumber #251 cucumber-ruby-wire#13
  All checks have failed

[mxygem]

Thanks @mlvandijk! I appreciate the time! WRT contributors, the members listed were pulled directly from Github using the following command and then I added myself to them:

curl https://api.github.com/repos/cucumber/github-issue-stats/contributors | jq 'sort_by(.login) | [.[] | {user: .login, url: .html_url}]'

@mattwynne / @aslakhellesoy Now that these have been approved how would you like me to move forward? Also, are the Ruby tests broken?

[mlvandijk]

@js That answers my 1st question. Thnx!

[mxygem]

Unless anyone has objections, I'm going to go through and merge things today. I've also got a request from @maxmeyer to add a changelog to aruba-getting-started which I'll do too.

[mxygem]

Everything except for the new changelog added in the aruba-getting-started repo has been merged! Almost done with this!

[mxygem]

I think we're all set here! Going to close this out, we should probably extract the template I wrote above to be a guide for any new repos created?

[mvz]

@jaysonesmith I'm currently updating the Aruba change log with new changes, and I'm finding adding all the links for issues and users is becoming quite a chore. Is there any way to automate this?

Update: I have solved this problem by using footnote-style linking for both issues and users. This way, I can first add all the entries, and then add all the new links at once.

[mxygem]

Heya @mvz! I can certainly understand how that could be. For the ruby repo there's a script we run to handle it. We've also got #255 to help out, just haven't done it. >.<

[mvz]

Oh, #255 looks useful!

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.