From b83690f7835761fc74247c77cf7aaac7948af7bf Mon Sep 17 00:00:00 2001 From: Mohammad Jangda Date: Thu, 12 Jul 2018 16:49:19 -0400 Subject: [PATCH 1/3] Add publish/release instructions --- CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 080e248bc..e220ccc19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,10 +2,41 @@ Thanks for contributing to the VIP Javascript library. There are some guidelines to ensure we have consistency across the CLI and web interfaces. -## Adding commands +## Coding Standards + +TODO + +## Developing + +### args package + +TODO + +### Adding commands * New command names should use the singular case (e.g. site vs sites) -## Adding libraries +### Adding libraries New libraries should generally support both CLI and web contexts, though some cases that won't make sense (e.g. formatting for CLI output). Ensuring the libraries are useful everywhere will allow us to offer consistent experiences regardless of the interface. + +## Releasing + +Note: We use `publish-release` for some pre-publish confidence checks to avoid common mistakes. + +### Major / Minor Versions + +1. Set the version: `npm version minor` or `npm version major` +1. `npm run publish-please` +1. `git push --tags` +1. Edit the release in Github to include a description of the changes and publish. +1. Bump the version to the next minor: `npm --no-git-tag-version version preminor` +1. Commit and push. + +Note: doing the last two steps can is useful for debugging in case someone is running the dev version (via `vip version`). + +### Patch Version + +For a critical fix, we can `git checkout` a previous release and cherry-pick or apply specific changes. This is especially useful for security releases and if there are already some bigger changes in the master branch and you don't want to push a normal release. + +The release steps are the same as `Major / Minor` except that we would run `npm version patch`. From d2385bf6dd737ba4b1e48af7d68111a5f18699bb Mon Sep 17 00:00:00 2001 From: Mohammad Jangda Date: Thu, 12 Jul 2018 22:36:56 -0400 Subject: [PATCH 2/3] Add note about changelog in README --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e220ccc19..3f61e8fad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,10 @@ New libraries should generally support both CLI and web contexts, though some ca Note: We use `publish-release` for some pre-publish confidence checks to avoid common mistakes. +### Changelog + +For all releases, we should include a changelog in the `README.md` file at the root of this repo. + ### Major / Minor Versions 1. Set the version: `npm version minor` or `npm version major` From d0b969dcdd927a5655255e9a5a0c457e9e8869a0 Mon Sep 17 00:00:00 2001 From: Mohammad Jangda Date: Fri, 13 Jul 2018 17:03:40 -0400 Subject: [PATCH 3/3] Lots more details on the release Including considerations for config and clearer details on patching. --- CONTRIBUTING.md | 55 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f61e8fad..3d44b490a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ TODO ## Developing -### args package +### `args` package TODO @@ -20,27 +20,52 @@ TODO New libraries should generally support both CLI and web contexts, though some cases that won't make sense (e.g. formatting for CLI output). Ensuring the libraries are useful everywhere will allow us to offer consistent experiences regardless of the interface. -## Releasing +## Releasing / Publishing -Note: We use `publish-release` for some pre-publish confidence checks to avoid common mistakes. +### Pre-publish Checks -### Changelog +We use [`publish-please`](https://github.com/inikulin/publish-please) for some pre-publish confidence checks to avoid common mistakes. -For all releases, we should include a changelog in the `README.md` file at the root of this repo. +Further checks can be added to this flow as needed. -### Major / Minor Versions +### Pre-publish Tasks -1. Set the version: `npm version minor` or `npm version major` -1. `npm run publish-please` -1. `git push --tags` -1. Edit the release in Github to include a description of the changes and publish. +As part of the publish flow, we run the `prepareConfig:publish` task on `prepack`. This copies over "production" config values to your working copy to make sure the release includes those instead of development values. + +We use `prepack` because: + +- `prepareConfig:local` runs on `npm build` and we want to make sure those values are overriden. +- This is the latest npm event that we can run on before publishing. (Note: we tried `prepublishOnly` but files added during that step [don't get included in the build](https://github.com/Automattic/vip/commit/c7dabe1b0f73ec9e6e8c05ccff0c41281e4cd5e8)). + +### New Releases + +Prepare the release by making sure that: + +1. All relevant PRs have been merged. +1. The release has been tested across macOS, Windows, and Linux. +1. The [changelog](https://github.com/Automattic/vip/blob/master/README.md#changelog) has been updated. +1. All tests pass and your working directory is clean (we have pre-publish checks to catch this, just-in-case). + +Then, let's publish: + +1. Set the version (via `npm version minor` or `npm version major` or `npm version patch`) + 1. For most regular releases, this will be `npm version minor`. +1. Publish the release to npm (`npm run publish-please`) +1. Push the tag to GitHub (`git push --tags`) +1. Edit [the release on Github](https://github.com/Automattic/vip/releases) to include a description of the changes and publish (this can just copy the details from the changelog). 1. Bump the version to the next minor: `npm --no-git-tag-version version preminor` -1. Commit and push. +1. Commit and push (`git add -u` + `git commit` + `git push origin master`). + +Once released, it's worth running `npm i -g @automattic/vip` to install / upgrade the released version to make sure everything looks good. + +### Patching Old Releases -Note: doing the last two steps can is useful for debugging in case someone is running the dev version (via `vip version`). +There may be times when we need to push out a critical fix to the most recent release (or several past releases) such as for patching security issues or major bugs. This can be complicated by the fact that we may have some larger changes already merged into the `master` branch. -### Patch Version +For these cases: -For a critical fix, we can `git checkout` a previous release and cherry-pick or apply specific changes. This is especially useful for security releases and if there are already some bigger changes in the master branch and you don't want to push a normal release. +1. `git checkout` to the tag of the previous release. +1. Apply the fix (either manually or by cherry-picking). +1. Follow the release steps outlined above (as a `patch` release). -The release steps are the same as `Major / Minor` except that we would run `npm version patch`. +Then, repeat for any additional versions that we need to patch.