Have a human-readable changelog

[wtimme]

In order to support automatic releases and increase transparency, I suggest we follow Keep a Changelog.

This would involve

• create CHANGELOG.md
• add contents from keepachangelog.org

Whenever a contributor adds a feature/bugfix/refactoring that is worth mentioning, it is manually added to CHANGELOG.md.

Follow-ups

After we have a working CHANGELOG.md, we can use it to automatically populate "What's New" when creating a new Beta release.

[bryceco]

I admit that lots of projects have a changelog. Do people actually read them? Does anybody really care what changed between 1.6 and 1.6.1? And if you do care the App Store already records it for released versions.

[wtimme]

Do people actually read them? Does anybody really care what changed between 1.6 and 1.6.1?

I do, yes. I'm sure some of the TestFlight testers do as well.

And if you do care the App Store already records it for released versions.

Yeah, but where is that data coming from? You have to put it in yourself, requiring manual effort. Once a CHANGELOG.md is put in place and maintained, we can derive the "What's New" texts from it, automatically. In addition, we can use the information for GitHub releases, making it easier for people to track their issue and in which version it was released.

What are the downsides of having a changelog?

[bryceco]

When I release a new TestFlight version I go back through the changeset log and pick out the significant user-facing changes that are relevant to testers. There might be refactoring that's important for devs but doesn't change functionality.

I guess for me the downside is that when I post something to TestFlight it asks me about the changes and I fill in the box. With changelog.md I have to be proactive and if I don't remember to update it then we have uninformed testers and stale data.

[wtimme]

I go back through the changeset log

Exactly. Instead, you could go back through the human-readable CHANGELOG.md and simply copy the information.

There might be refactoring that's important for devs but doesn't change functionality.

Yes, I agree that putting everything in the CHANGELOG.md (for example #432) does not make sense. But I think that this is something that we can discuss in the particular pull requests: For every feature/bugfix, a developer is asked to update the CHANGELOG.md. If the pull request only contains a technical refactoring, we can use the pull request discussion to decide whether we want to include the refactoring in the changelog.

I guess for me the downside is that when I post something to TestFlight it asks me about the changes and I fill in the box.

With CHANGELOG.md and automation, you'd no longer have to.

With changelog.md I have to be proactive and if I don't remember to update it then we have uninformed testers and stale data.

Yes, and the same argument applies to the manual search through the Git commit history: You could miss a commit/merge, resulting in uninformed testers and stale data just the same. The difference is that with the CHANGELOG.md, we have a standardized, widely accepted way of noting down the changes, in addition allowing us to automate the release process even further.

[tordans]

+1 for a changelog – that is easily created by helper tools, so its not too much work.

Why?

• I like to stay up to date by reading the changelog, eg. the one from iD https://github.com/openstreetmap/iD/blob/develop/CHANGELOG.md
• Its a great way to promote the release and thereby the app in the community
  • Eg. i think iD creates a post in some of the mailinglists whenever a new release is live
  • It would allow to link to something in weeklyOSM (one can recommend links at https://osmbc.openstreetmap.de/article/create)
  • There are people collecting osm software updates, especially https://twitter.com/hashtag/OSMSoftwareWatchList?src=hashtag_click, but the website is down ATM https://wambachers-osm.website/index.php/osm-software-watchlist

[tordans]

In https://github.com/bryceco/GoMap/issues/211 I referenced https://github.com/release-drafter/release-drafter which might be a tool that can help with drafting the changelog automatically.

[ghost]

It's also useful for historical reasons, to understand which features were available to whom when. Wikidata uses version numbers for enhancing statements, too, and a human-readable list of changes accompanying each version helps a lot.

[tordans]

FYI: I asked Quincy about how they do it with iD at https://osmus.slack.com/archives/CBK3JLUJU/p1599768783029300 - its a manual process based on https://github.com/openstreetmap/iD/milestones?state=closed and https://github.com/openstreetmap/iD/compare/release...develop.

[bryceco]

Okay, if someone wants to create a changelog.md seeded with the historic versions from the App Store then I'll merge it.