[RFC] New changelog process

[ds300]

Problem

With the Android launch just around the corner, we need to figure out a way to manage independent release notes for iOS and Android.

For iOS we currently generate release notes based on the user_facing portion of a changelog entry in CHANGELOG.yml.

Here's the relevant code in our fastlane script

eigen/fastlane/Fastfile

Lines 43 to 44 in d88d47b

	notes = upcoming['user_facing'] || []
	beta_readme = "## #{upcoming['version']} - #{commit} \n\n - #{notes.join "\n - "} \n\n"

Also I think many of us are frustrated by the current process's tendency to cause merge conflicts, so it would be nice to simultaneously find a way around that.

Potential Solutions

Extending the current process

We can't simply replace the user_facing field with two fields: ios_user_facing and android_user_facing because we need to be able to release the app independently on both platforms.

But what we could do is replace CHANGELOG.yml with CHANGELOG_IOS.yml and CHANGELOG_ANDROID.yml.

Pros:

• Quick change to make
• Close to what we already do, so not much learning involved.

Cons:

• Ultimately most changes product engineers make will be cross-platform, so they will often need to touch two files instead of one. Double merge conflicts!
• What to do with dev-only changes? Duplicate them on both platforms or move them to their own changelog file? I personally find it useful to cross-reference dev-only changes with user-facing changes, so duplicating would be helpful for me at least. But, again, who wants to do all that copy-pasting and merge conflict resolution?

Building a new system based on PR descriptions (proposed solution)

We could use PR descriptions as a source of truth to avoid merge conflicts, manual duplication, and making extra 'update changelog' commits.

How would that work?

PR template section + danger validation

We'd add a new section to the PR template. Something along the lines of:

### Changelog updates
<!-- 📝 Please fill out at least one of these sections. -->
<!-- ⓘ 'User-facing' changes will be published as release notes. -->
<!-- ⌫ Feel free to remove sections that don't apply. -->
<!-- • Write a markdown list or just a single paragraph, but stick to plain text. -->
<!-- 🤷‍♂️ Replace this entire block with the hashtag `#nochangelog` to avoid updating the changelog. -->
#### Cross-platform user-facing changes
- 
#### iOS user-facing changes
- 
#### Android user-facing changes
- 
#### Dev changes
- 

And then we'd add a danger rule to validate the requirements outlined in the comments.

Log collation tooling

Firstly, we'd archive the current CHANGELOG.yml and replace it with two markdown files: CHANGELOG.ios.md, and CHANGELOG.android.md. Both of which would feature very visible comments at the top saying something along the lines of "DON'T UPDATE THESE MANUALLY" and we could add lint-staged rules to help reinforce that.

Every time we ship a beta for a particular platform we'll need to collect the user-facing and dev-only changes that have been added since the last public release for the platform. This should be straightforward using git tags, the GitHub API, and some custom scripting.

The release notes will be submitted with the beta, and meanwhile we'll add a commit on master to do one of the following:

• Create a new entry in the platform's changelog markdown file like the following

  ## v6.8.0
  - Status: Beta
  - Build number: 6.8.0-2021.03.05.14
  - User-facing changes:
    - Added new header styles (David, Brian)
    - Fixed typography on Artwork page (Lily)
  - Dev changes:
    - Removed unused Button component (Steve)

  We can get people's names from their github accounts, although I'm not sure it is helpful to include the names when submitting public release notes to the app store or play store, so we can decide whether we want to keep doing that.

• Update the build number and change lists for an existing beta entry.

Then when we promote the app for that platform we can set the status to In review. And then when we press the release button and do the whole 'prepare for the next release' step we can add some scripting to set the status to 'Released'.

Pros:

• Great DX

Cons:

• Nontrivial amount of custom tooling to implement & maintain.

Corollary: Having independent version numbers.

Each approach implies the need to maintain two separate version numbers for iOS and Android. I can't see a sane way of having only one version number that is incremented when each platform makes an independent release, and orchestrating synchronized releases is obviously problematic.

So I'd propose we augment our app.json file and fastlane scripts to support platform-independent version numbers.

How is this RFC resolved?

If we reach a consensus to proceed with the proposed solution, we can plan a spike to investigate any technical risks, or simply forge ahead with implementing our solution if it's clear what needs to happen. If we don't reach a consensus we can extend the existing system by default, or try to find an alternative.

[iskounen]

The new system based on PR descriptions sounds like it would be the most intuitive way for engineers on other product teams to follow best-practices around maintaining the changelog. You guys have already done the work to standardize PR descriptions and have been using it consistently, so this approach seems like an extension of those efforts.

One suggestion would be to clarify on what "consensus" means for resolving this RFC, and whose consensus you would like to gather. I assume that this means a majority of attendees at the Mobile Practice where this is voted upon, but I could be wrong.

[MounirDhahri]

This seems reasonable to me. The only concern I have would be with the Dev changes section that would include mainly android specific changes over the next few weeks. But I think that’s fine since we don’t show dev changes to users.

It’s also good to know that this will help us fix the issue with the changelog merge conflicts.

[ds300]

One suggestion would be to clarify on what "consensus" means for resolving this RFC, and whose consensus you would like to gather. I assume that this means a majority of attendees at the Mobile Practice where this is voted upon, but I could be wrong.

I suppose by 'consensus' I mean 'nobody is against the idea of implementing the PR-based workflow'. And anyone in the engineering org is welcome to offer their opinion. I'll publicise this RFC at team standup on Monday. We can also discuss further at the mobile practice next week.

[ds300]

The only concern I have would be with the Dev changes section that would include mainly android specific changes over the next few weeks. But I think that’s fine since we don’t show dev changes to users.

That's a good point. One option to mitigate noise in changelogs is to also have android-specific dev changes and ios-specific dev changes. Once we get the tooling in place tweaking this stuff would be simple.

[pvinis]

Nothing more to say besides:

Let's do it! I like the suggestion a lot, and I want to help do this.

Oh, also, about

We can get people's names from their github accounts, although I'm not sure it is helpful to include the names when submitting public release notes to the app store or play store, so we can decide whether we want to keep doing that.
I'd keep it. It adds a nice personal touch in the changes. Feels like those Slack updates or Discord etc.

[brainbicycle]

This looks great! 🎉 🙌

One thing I'll note is right now the changelog is only used for release notes for betas, when we release to App Store we still manually specify release notes, I would be in favor of continuing that just so devs don't have to worry about their changelog entries being user friendly and allowing us to personalize the release notes should we want to.

Other thing I am thinking is nice about changelog now being updated on every commit vs. when a beta is shipped is that we can look at it at anytime on a branch and see what changes are in that current build, but I think we could probably easily accommodate that with this proposal with some script to allow for similar.

Very much in favor!

[ds300]

Thanks for the feedback everyone!

Looks like we'll resolve with the following caveats:

• We shouldn't imply that user-facing changes will end up in the public release notes, for iOS at least (need to check android release promotion process).
• It might be nice to find a way to see changes that haven't made it into a beta release yet (potentially a 'not yet deployed' section at the top of each changelog?)
• We can add platform-specific options for dev-only changes too

Next step for me is to create Jira tickets for

• Spike to find out how our release process needs to change to support this (git tags etc), and how to switch seamlessly.
• PR description parser to extract change notes
• Danger check
• Changelog updater
• Making the changelog updater fire on every commit to master. Also after beta deploys, promotions, and releases.

[ds300]

https://artsyproduct.atlassian.net/browse/CX-1209