From 8f0e717496d39d1eb92ab7d6b24d170add3ce175 Mon Sep 17 00:00:00 2001 From: Tan Wang Leng Date: Sat, 4 May 2019 12:57:09 +0800 Subject: [PATCH 1/7] maintainerGuide.md: Add missing -a option when commiting vue-strap Without the -a option, the modified files are not added, so we end up doing an empty commit rather than committing the changes. --- docs/devGuide/maintainerGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devGuide/maintainerGuide.md b/docs/devGuide/maintainerGuide.md index 31f4bd5241..a69d7c576b 100644 --- a/docs/devGuide/maintainerGuide.md +++ b/docs/devGuide/maintainerGuide.md @@ -72,7 +72,7 @@ You should see changes in `vue.min.js`, `vue-strap.js.map` and `vue-strap.min.js 2. Commit the new changes. ``` -$ git commit -m 'Update dist' +$ git commit -am 'Update dist' ``` 3. Tag the new commit with the new version number, whereby `XYZ` is the incremented number of the previous release. From 50a71e5d32b9e4ef631f69d91046d8f1b4d79df5 Mon Sep 17 00:00:00 2001 From: Tan Wang Leng Date: Sat, 4 May 2019 13:02:07 +0800 Subject: [PATCH 2/7] maintainerGuide.md: Move `npm version` step before updating test files When building a website, MarkBind puts the version number in a meta tag inside the generated HTML files. Therefore, functional tests' expected files need to be updated, whenever there is a change in the version number, so that the tests will continue to pass. We asked maintainers to update the test files before the version number is actually incremented, which doesn't make sense because the generated HTML files will not have the new version number yet. Let's re-arrange the steps so that the updating is done after the version number is incremented. --- docs/devGuide/maintainerGuide.md | 42 ++++++++++++++++---------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/devGuide/maintainerGuide.md b/docs/devGuide/maintainerGuide.md index a69d7c576b..acc7657635 100644 --- a/docs/devGuide/maintainerGuide.md +++ b/docs/devGuide/maintainerGuide.md @@ -112,7 +112,27 @@ $ git commit -m 'Update vue-strap version to v2.0.1-markbind.XYZ' * **Note:** We uniquely do this for each MarkBind release (rather than spontaneously update the vue-strap files for each affected PR), in order to reduce unnecessary merge conflicts. It also makes it easier for the maintainers to vet the changes. -2. Rebuild the test files. +2. Do an `npm version` to increment the version number. Which to increment (`patch`, `minor` or `major`) depends on what PRs are merged for the new version, which means you must know beforehand about the changes. + +* If there are no significant changes, a `patch` is sufficient: + +``` +$ npm version patch +``` + +* If there are significant changes (e.g. breaking changes, new release), a `minor` release is needed: + +a. Update the version number inside `src/lib/markbind/package-lock.json` and `src/lib/markbind/package.json` manually. This is because `npm version` will not automatically update the numbers from the outside. + +b. Do a `npm version minor` as per normal. + +``` +$ npm version minor +``` + +* We rarely do `major` releases, but if necessary, the steps are the same as the `minor` release (just change `minor` to `major`). + +3. Rebuild the test files. ``` # on Unix @@ -144,26 +164,6 @@ However, if there are any extra lines changed, that means that someone screwed u Only when it is fixed do you proceed with the next step of the release procedure. -3. Do an `npm version` to increment the version number. Which to increment (`patch`, `minor` or `major`) depends on what PRs are merged for the new version, which means you must know beforehand about the changes. - -* If there are no significant changes, a `patch` is sufficient: - -``` -$ npm version patch -``` - -* If there are significant changes (e.g. breaking changes, new release), a `minor` release is needed: - -a. Update the version number inside `src/lib/markbind/package-lock.json` and `src/lib/markbind/package.json` manually. This is because `npm version` will not automatically update the numbers from the outside. - -b. Do a `npm version minor` as per normal. - -``` -$ npm version minor -``` - -* We rarely do `major` releases, but if necessary, the steps are the same as the `minor` release (just change `minor` to `major`). - 4. Push the new commit and version tag generated by `npm` (change `vA.B.C` to the new version's string accordingly). ``` From 4cdc24b98f5f0b99acc5bd2ed824e2c8d6be1ce9 Mon Sep 17 00:00:00 2001 From: Tan Wang Leng Date: Sat, 4 May 2019 13:15:14 +0800 Subject: [PATCH 3/7] maintainerGuide.md: Add `git commit --amend` after updating test files The changes in the test files (together with other changes, such as the `package-lock.json` changes made in step 2), needs to be combined with the version commit, rather than being a separate commit on its own. Let's add instructions to guide maintainers on how such amendments can be done. --- docs/devGuide/maintainerGuide.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/devGuide/maintainerGuide.md b/docs/devGuide/maintainerGuide.md index acc7657635..5dcf0908f0 100644 --- a/docs/devGuide/maintainerGuide.md +++ b/docs/devGuide/maintainerGuide.md @@ -122,9 +122,9 @@ $ npm version patch * If there are significant changes (e.g. breaking changes, new release), a `minor` release is needed: -a. Update the version number inside `src/lib/markbind/package-lock.json` and `src/lib/markbind/package.json` manually. This is because `npm version` will not automatically update the numbers from the outside. +a. Do a `npm version minor` as per normal. -b. Do a `npm version minor` as per normal. +b. Update the version number inside `src/lib/markbind/package-lock.json` and `src/lib/markbind/package.json` manually. This is because `npm version` will not automatically update the numbers from the outside. (Note: You do not have to commit these changes immediately, as we also have to rebuild the test files in the next step anyway.) ``` $ npm version minor @@ -162,28 +162,33 @@ index 779f279..bb3c602 100644 However, if there are any extra lines changed, that means that someone screwed up the functional tests, and needs to be fixed accordingly! -Only when it is fixed do you proceed with the next step of the release procedure. +4. The changes that you have made in the last two steps need to be combined together with the version commit generated by `npm version`. Therefore, amend the version commit and version tag by doing the following (change `vA.B.C` to the new version's string accordingly). -4. Push the new commit and version tag generated by `npm` (change `vA.B.C` to the new version's string accordingly). +``` +$ git commit -a --amend --reuse-message vA.B.C +$ git tag --force vA.B.C # to reassign the tag to the newly amended commit +``` + +5. Push the new commit and version tag generated by `npm` (change `vA.B.C` to the new version's string accordingly). ``` $ git push upstream master $ git push upstream vA.B.C ``` -5. Do an `npm publish`. You should receive a notification by `npm` that the publish is successful. +6. Do an `npm publish`. You should receive a notification by `npm` that the publish is successful. ``` $ npm publish ``` -6. If you used `npm link` for your project, ensure that you try the new release on another platform that doesn't use `npm link`, so that we can be sure the end-users can install and use the new version. +7. If you used `npm link` for your project, ensure that you try the new release on another platform that doesn't use `npm link`, so that we can be sure the end-users can install and use the new version. a. Just do `npm i -g markbind-cli@A.B.C` on the different platform and... b. ... play around with the new MarkBind version to ensure that it works. -7. Ensure that the documentation at markbind.org is deployed correctly. +8. Ensure that the documentation at markbind.org is deployed correctly. Since #701, the deployment is automated. @@ -195,7 +200,7 @@ $ markbind build $ markbind deploy ``` -8. Draft a new release on GitHub. +9. Draft a new release on GitHub. a. Go to the Markbind release page at https://github.com/MarkBind/markbind/releases. @@ -316,6 +321,6 @@ test: Add diff printing for easier debugging (#632) f. Click "Publish release". -9. Finally, announce the new release on our Slack channel (replace `A.B.C` with the new version). Congrats! +10. Finally, announce the new release on our Slack channel (replace `A.B.C` with the new version). Congrats! * Published: `npm i -g markbind-cli@A.B.C` From 44c4087b1e8e63dea108c75d26a53ba021805805 Mon Sep 17 00:00:00 2001 From: Tan Wang Leng Date: Sat, 4 May 2019 13:29:45 +0800 Subject: [PATCH 4/7] maintainerGuide.md: Ask maintainer to close version milestone The newly released version's milestone will no longer be necessary after the release. --- docs/devGuide/maintainerGuide.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/devGuide/maintainerGuide.md b/docs/devGuide/maintainerGuide.md index 5dcf0908f0..ffceed9646 100644 --- a/docs/devGuide/maintainerGuide.md +++ b/docs/devGuide/maintainerGuide.md @@ -200,7 +200,11 @@ $ markbind build $ markbind deploy ``` -9. Draft a new release on GitHub. +9. Close the [issue milestone on GitHub](https://github.com/MarkBind/markbind/milestones) tied to that version. + + a. Please also create a new milestone for the next iterations. Recommended to have at least two version milestones opened. + +10. Draft a new release on GitHub. a. Go to the Markbind release page at https://github.com/MarkBind/markbind/releases. @@ -321,6 +325,6 @@ test: Add diff printing for easier debugging (#632) f. Click "Publish release". -10. Finally, announce the new release on our Slack channel (replace `A.B.C` with the new version). Congrats! +11. Finally, announce the new release on our Slack channel (replace `A.B.C` with the new version). Congrats! * Published: `npm i -g markbind-cli@A.B.C` From e5b8f8449d42eaba7031821174e1be4a17f8e020 Mon Sep 17 00:00:00 2001 From: Tan Wang Leng Date: Sat, 4 May 2019 13:35:01 +0800 Subject: [PATCH 5/7] maintainerGuide.md: Add section for new maintainers --- docs/devGuide/maintainerGuide.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/devGuide/maintainerGuide.md b/docs/devGuide/maintainerGuide.md index ffceed9646..c76c0f53c4 100644 --- a/docs/devGuide/maintainerGuide.md +++ b/docs/devGuide/maintainerGuide.md @@ -55,6 +55,14 @@ Please follow the [commit message convention](https://oss-generic.github.io/proc # Doing a Release +## Prerequisites for New Maintainers + +Ensure that: + +* You have the rights to push to master branch on [MarkBind's repository](https://github.com/MarkBind/markbind), and also to make new releases. +* You have the rights on [npm](https://www.npmjs.com/) to make a new release. + * You need to login to npm on your terminal with `npm adduser` first, before you can publish packages to npm. + ## Building Vue-Strap 1. Ensure that you are on the root directory on vue-strap, then execute: From 00d1407f8a5ee7263d8d518fc2ad076a5967c5b6 Mon Sep 17 00:00:00 2001 From: Tan Wang Leng Date: Fri, 10 May 2019 20:13:54 +0800 Subject: [PATCH 6/7] maintainerGuide.md: Add hyperlink to docs deployment PR --- docs/devGuide/maintainerGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devGuide/maintainerGuide.md b/docs/devGuide/maintainerGuide.md index c76c0f53c4..c28f39a685 100644 --- a/docs/devGuide/maintainerGuide.md +++ b/docs/devGuide/maintainerGuide.md @@ -198,7 +198,7 @@ $ npm publish 8. Ensure that the documentation at markbind.org is deployed correctly. -Since #701, the deployment is automated. +Since [#701](https://github.com/markbind/markbind/pull/701), the deployment is automated. However, if it doesn't deploy properly for the release, do the following: From c8dce8661c36e3366f2f2a0e1329dbf0198bdf06 Mon Sep 17 00:00:00 2001 From: Tan Wang Leng Date: Fri, 10 May 2019 20:18:52 +0800 Subject: [PATCH 7/7] maintainerGuide.md: Change "Do a(n)" to "Run" --- docs/devGuide/maintainerGuide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/devGuide/maintainerGuide.md b/docs/devGuide/maintainerGuide.md index c28f39a685..e91e60a09b 100644 --- a/docs/devGuide/maintainerGuide.md +++ b/docs/devGuide/maintainerGuide.md @@ -120,7 +120,7 @@ $ git commit -m 'Update vue-strap version to v2.0.1-markbind.XYZ' * **Note:** We uniquely do this for each MarkBind release (rather than spontaneously update the vue-strap files for each affected PR), in order to reduce unnecessary merge conflicts. It also makes it easier for the maintainers to vet the changes. -2. Do an `npm version` to increment the version number. Which to increment (`patch`, `minor` or `major`) depends on what PRs are merged for the new version, which means you must know beforehand about the changes. +2. Run `npm version` to increment the version number. Which to increment (`patch`, `minor` or `major`) depends on what PRs are merged for the new version, which means you must know beforehand about the changes. * If there are no significant changes, a `patch` is sufficient: @@ -130,7 +130,7 @@ $ npm version patch * If there are significant changes (e.g. breaking changes, new release), a `minor` release is needed: -a. Do a `npm version minor` as per normal. +a. Run `npm version minor` as per normal. b. Update the version number inside `src/lib/markbind/package-lock.json` and `src/lib/markbind/package.json` manually. This is because `npm version` will not automatically update the numbers from the outside. (Note: You do not have to commit these changes immediately, as we also have to rebuild the test files in the next step anyway.) @@ -184,7 +184,7 @@ $ git push upstream master $ git push upstream vA.B.C ``` -6. Do an `npm publish`. You should receive a notification by `npm` that the publish is successful. +6. Run `npm publish`. You should receive a notification by `npm` that the publish is successful. ``` $ npm publish