Deployment And Publishing

• Setting up Git Flow
• Step-by-Step instructions for a regular release
• Instructions to hotfix/patch an earlier release

Setup

1. git flow init
2. Which branch should be used for bringing forth production releases? master
3. Which branch should be used for integration of the "next release"? dev
4. How to name your supporting branch prefixes?
   • Feature branches?: return¬
   • Release branches?: return¬
   • Hotfix branches?: return¬
   • Support branches?: return¬
   • Version tag prefix? [] return¬

Step-by-Step for a typical release

1. Ensure you have latest on both dev and master branches.

2. Checkout the dev branch.

   git checkout dev

3. Start a release by running.

   git flow release start [sematic-version-name-here]

4. Do all of the updates necessary for documenting the new version:

   • Update the version number in ./package.json.
   • Do npm install to ensure ./package-lock.json is updated as well. The version number change should theoretically be the ONLY change in this file.
   • Update ./src/versions.js.
   • Add new entry in ./CHANGELOG.md.
   • If there have also been changes to the Documentation website (as well as library components):
     • Update the version number in ./docs/package.json.
     • Do npm install in the /docs directory to update ./docs/package-lock.json. The version number should be the only change.
     • Add new entry in ./docs/CHANGELOG.md.

5. Commit these changes (to the release candidate branch).

   • Usually I put a commit message like: feat: update version to [sematic-version-name-here] or feat: update version to [sematic-version-name-here] (and docs version to [docs-semantic-version])

6. OPTIONAL: Push the release branch to the remote.

   git push --set-upstream origin release/[branch-name-here] OR
   git flow release publish [sematic-version-name-here]

   • Usually this step is not needed; that's why it's indicated as optional.

7. Finish the release by running.

   git flow release finish [sematic-version-name-here]

   • When prompted to enter a commit message for the tag, I usually enter a message like: Tag version 10.7.4.
   • Note this is usually done in VI editor, so you'll need to hit I to enter insert mode, type the message, hit Enter to go to the next line, hit Esc to exit insert mode, type colon (:) and then wq to save and exit (write/quit).

8. Push the dev branch.

   git push

9. Push the tag.

   git push origin [sematic-version-name-here] // pushes just single tag

10. Run the publish script.

    npm publish

    • This will compiles /src into /lib, publish the new version to the NPM registry, check out master, pushes master, and then checks out dev branch again.
    • If you have MFA (multi-factor authorization) setup with NPM, you might need to provide an OTP (one-time-pad) code from your authenticator application in order to do the publish.

11. Update GitHub Releases - add release notes for the new version. The ones automatically generated by the "generate release notes" button that lists merged PRs are just fine for this.

12. Profit!

Step-by-Step to "Hotfix" a past version

Sometimes it is necessary to release a newer patch of an older version of React CM UI. This often is required when fixing bugs in a release or hotfix branch of the HC back-office client application, whenever a newer React CM UI version has been published than the one referenced by the HC in said release or hotfix branch..

Example: the hotfix or release candidate is using React CM UI 6.1.0 but there is now also a React CM UI 6.2.0 (or 7.0.0, etc.). But we need to fix a blocking issue in 6.1.x, i.e. we require a 6.1.1.

This is a somewhat odd procedure, and the existing git flow automation won't do the right thing, so here are the manual steps.

1. Create a new hotfix branch from the tag of the version we wish to base things on. Using our example of hot-fixing a 6.1.1 from 6.1.0 when latest is say 6.2.0, do this:

   git checkout -b hotfix/6.1.1 6.1.0

2. Do all of the code fixes, and also bump the version in package.json and update CHANGELOG.md in this branch. Important note for the Changelog: we want to keep it chronological. So, eventually when we merge back to dev, we will want the entry for version 6.1.1 on the top (above a higher version that was released earlier, e.g. 6.2.0).

3. Do npm publish --tag [some tag name] to publish this version of React CM UI. [some tag name] should be some "kebab-case" identifier that is terse but describes the reason for the patch, e.g. date-picker-hotfix. It is important to include an npm tag so that this publish does not move the latest tag. Moving latest is the default behavior, but we don't want that in this case; we want latest to continue pointing to the highest numbered version, latest and greatest, e.g. 6.2.0 or whatever. Note that the npm post-publish command runs some git commands (pushing dev and master branches) and this may fail (because we might not have merged things or be completely up-to-date in dev and master); that's okay. As long as the npm publish step itself succeeds, all is good.

4. Switch back to the hotfix branch and manually create and push a Git tag from the latest commit in the hotfix branch. This is very important, in case we have the pleasure of doing this again, e.g. we need 6.1.2!

   git tag -a 6.1.1 -m "Tag version 6.1.1"
git push origin 6.1.1

5. Now merge changes from the hotfix branch into dev. This can be done with a local merge, or a PR, or however you like. Be on lookout for conflicts! Some, like package.json version and CHANGELOG.md are expected and obvious, but of course the actual code could conflict too!

6. At this point, we can delete the hotfix branch. And we should do another regular release from dev branch (i.e. let's also produce a 6.2.1 that has all the goodness from 6.2.0 plus our new bug fix).