Skip to content

Latest commit

 

History

History
80 lines (50 loc) · 3.9 KB

generate-changelog.md

File metadata and controls

80 lines (50 loc) · 3.9 KB
Raw

Generate changelog

Point people: @alloy, @kelset, @turnrye

This repo contains a script that will generate a markdown formatted list of changes between two given git references (e.g. tags).

The script is a little more complex than one might expect for the following reasons:

  • Attributing changes to the author’s github handle requires fetching the commit metadata from the github API, rather than rely on a local clone of the react-native repo.

  • Due to how react-native’s release process works, we want to be able to exclude previously cherry-picked commits from the changelog entry of a next version.

    However, with git, cherry-picked commits will have different commit hashes than their original counterparts–as they exist in the master branch. Because of this, the next version’s stable branch will include the same changes, except using their original commit hash. This makes it impossible to exclude these commits without further work.

    For this reason, the script will parse the ‘referential revision’–which is added to each commit message by Facebook’s infrastructure–and use it to resolve to the original commit in the master branch. This resolved commit’s hash is then used in the changelog entry, so the script can find and exclude it from the next version’s entry.

    This cannot be done via the github API and thus relies on a local clone of the react-native repo.

Setup

If you don’t already have a checkout of the react-native repo:

git clone https://github.com/facebook/react-native.git

…otherwise ensure it’s up-to-date:

pushd react-native
git checkout master
git pull
popd

Then clone this repo and install the script’s dependencies:

git clone https://github.com/react-native-community/releases.git
cd releases
yarn install

Finally, create a GitHub ‘personal access token’ that can be used by the script to fetch commit metadata from the GitHub API.

  1. Visit the token settings page.
  2. Generate a new token and only give it the public_repo scope.
  3. Store this token somewhere secure for future usage.

Usage

ℹ️ See yarn generate --help for a complete list of available options and their short-cuts.

Consider the case where version 0.62.0 has just been published and now we need a changelog entry for all changes between the previous version and the new version. The following command, where base and compare are tags that exist in the react-native repo, will do just that:

yarn generate --base v0.61.5 --compare v0.62.0 --repo ../react-native --token [GITHUB TOKEN]

The script will log, to stderr, informative details on its progress, as well as details on changes that might require follow-up work. The generated changelog entry will be printed to stdout and thus could be redirected to a file, if you so wish:

yarn -s generate […] > NEW_CHANGES.md

Post generation

If you’ve generated a changelog entry to accompany a new react-native release, the next steps are to:

  1. Add the resulting markdown to the CHANGELOG.md file.

  2. Remove empty sections from the generated markdown.

  3. Create a PR to update the CHANGELOG.md file in the repo and ask people to look for unexpected entries, ways to simplify the update, or ways to otherwise improve the update.

  4. Possibly improve the script by adding regression tests for entries that failed to generate as expected.