From 4c9166a9e1eeddef0c6c25abfce0763e54960b51 Mon Sep 17 00:00:00 2001 From: olivia Date: Wed, 7 Feb 2018 11:11:46 +0100 Subject: [PATCH] Add document on releasing a new version (#6745) Merge pull request 6745 --- docs/_docs/maintaining/avoiding-burnout.md | 4 +- docs/_docs/maintaining/index.md | 15 ++-- .../maintaining/merging-a-pull-request.md | 8 +- .../maintaining/releasing-a-new-version.md | 81 +++++++++++++++++++ 4 files changed, 95 insertions(+), 13 deletions(-) create mode 100644 docs/_docs/maintaining/releasing-a-new-version.md diff --git a/docs/_docs/maintaining/avoiding-burnout.md b/docs/_docs/maintaining/avoiding-burnout.md index e6acf402..ea9f88a2 100644 --- a/docs/_docs/maintaining/avoiding-burnout.md +++ b/docs/_docs/maintaining/avoiding-burnout.md @@ -7,11 +7,11 @@ title: "Avoiding Burnout" # 1. Use Jekyll -Maintainers of Jekyll should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our users but also because you may decide to stop using Jekyll and at that point you should also decide not to be a maintainer and find other things to work on. +Maintainers of Jekyll should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our users, but also because you may at some point decide to stop using Jekyll, and at that point you should also decide to stop being a maintainer and find other things to work on. # 2. No Guilt About Leaving -All maintainers can stop working on Jekyll at any time without any guilt or explanation (like a job). We may still ask for your help with questions after you leave but you are under no obligation to answer them. Like a job, if you create a big mess and then leave you still have no obligations but we may think less of you (or, realistically, probably just revert the problematic work). Like a job, you should probably take a break from Jekyll at least a few times a year. +All maintainers can stop working on Jekyll at any time without any guilt or explanation (like at a job). We may still ask for your help with questions after you leave but you are under no obligation to answer them. If you create a big mess and then leave you still have no obligations but we may think less of you (or, realistically, probably just revert the problematic work). Also, you should probably take a break from Jekyll at least a few times a year. This also means contributors should be consumers. If a maintainer finds they are not using a project in the real-world, they should reconsider their involvement with the project. diff --git a/docs/_docs/maintaining/index.md b/docs/_docs/maintaining/index.md index 383bc6ee..645030e2 100644 --- a/docs/_docs/maintaining/index.md +++ b/docs/_docs/maintaining/index.md @@ -8,13 +8,14 @@ permalink: /docs/maintaining/ Hello! This is where we document various processes for maintaining Jekyll. Being a maintainer for any Jekyll project is a big responsibility, so we put together some helpful documentation for various tasks you might do as a maintainer. -1. [Affinity teams & their captains](affinity-team-captain/) -2. [Triaging and issue](triaging-an-issue/) -3. [Reviewing a pull request](reviewing-a-pull-request/) -4. [Merging a pull request](merging-a-pull-request/) -5. [Avoiding burnout](avoiding-burnout/) -6. [Special Labels](special-labels/) +- [Affinity teams & their captains](affinity-team-captain/) +- [Triaging an issue](triaging-an-issue/) +- [Reviewing a pull request](reviewing-a-pull-request/) +- [Merging a pull request](merging-a-pull-request/) +- [Avoiding burnout](avoiding-burnout/) +- [Special Labels](special-labels/) +- [Releasing a new version](releasing-a-new-version/) Interested in becoming a maintainer? Here is some documentation for **contributors**: -1. [Becoming a maintainer](becoming-a-maintainer/) +- [Becoming a maintainer](becoming-a-maintainer/) diff --git a/docs/_docs/maintaining/merging-a-pull-request.md b/docs/_docs/maintaining/merging-a-pull-request.md index ec5599bb..c89e7e4a 100644 --- a/docs/_docs/maintaining/merging-a-pull-request.md +++ b/docs/_docs/maintaining/merging-a-pull-request.md @@ -16,7 +16,7 @@ All pull requests should be subject to code review. Code review is a [foundation We have [a helpful little bot](https://github.com/jekyllbot) which we use to merge pull requests. We don't use the GitHub.com interface for two reasons: 1. You can't modify anything on mobile (e.g. titles, labels) -2. Provide a consistent paper trail in the `History.markdown` file for each release +2. We like to provide a consistent paper trail in the `History.markdown` file for each release To merge a pull request, leave a comment thanking the contributor, then add the special merge request: @@ -30,12 +30,12 @@ The merge request is made up of three things: 1. `@jekyllbot:` – this is the prefix our bot looks for when processing commands 2. `merge` – the command -3. `+dev` – the category to which the changes belong +3. `+dev` – the category to which the changes belong. -The categories match the H3's in the history/changelog file, and they are: +The categories match the headings in the `History.markdown` file, and they are: 1. Major Enhancements (`+major`) – major updates or breaking changes to the code which necessitate a major version bump (v3 ~> v4) -2. Minor Enhancements (`+minor`) – minor updates (feature, enhancement) which necessitate a minor version bump (v3.1 ~> v3.2) +2. Minor Enhancements (`+minor`) – minor updates (with the labels `feature` or `enhancement`) which necessitate a minor version bump (v3.1 ~> v3.2) 3. Bug Fixes (`+bug`) – corrections to code which do not change or add functionality, which necessitate a patch version bump (v3.1.0 ~> v3.1.1) 4. Documentation (`+doc`) - changes to the documentation found in `docs/_docs/` 5. Site Enhancements (`+site`) – changes to the source of [https://jekyllrb.com](https://jekyllrb.com) found in `docs/` diff --git a/docs/_docs/maintaining/releasing-a-new-version.md b/docs/_docs/maintaining/releasing-a-new-version.md new file mode 100644 index 00000000..6d6750fc --- /dev/null +++ b/docs/_docs/maintaining/releasing-a-new-version.md @@ -0,0 +1,81 @@ +--- +title: "Releasing a new version" +--- + +**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. +{: .note .info } + +The most important thing to understand before making a release is that there's no need to feel nervous. Most things are revertable, and even if you do publish an incomplete gem version, we can always skip that one. Don't hestitate to contact the other maintainers if you feel unsure or don't know what to do next. + +### Bump the version + +The only important place you need to manually bump the version is in `lib/jekyll/version.rb`. Adjust that, and everything else should work fine. + +### Update the history document + +Replace the first header of the history document with a version milestone. This looks like the following: + +```diff +-## HEAD ++## 3.7.1 / 2018-01-25 +``` + +Adjust the version number and the date. The `## HEAD` heading will be regenerated next time a pull request is merged. + +Once you've done this, update the website by running the following command: + +```sh +bundle exec rake site:generate +``` + +This updates the website's changelog, and pushes the versions in various other places. + +It's recommended that you go over the `History.markdown` file manually one more time, in case there are any spelling errors or such. Feel free to fix those manually, and after you're done generating the website changelog, commit your changes. + +## Write a release post + +In case this isn't done already, you can generate a new release post using the included `rake` command: + +```sh +bundle exec rake site:releases:new[3.8.0] +``` + +where `3.8.0` should be replaced with the new version. Then, write the post. Be sure to thank all of the collaborators and maintainers who have contributed since the last release. You can generate a log of their names using the following command: + +```sh +git shortlog -sn master...v3.7.2 +``` + +where, again `v3.7.2` is the last release. Be sure to open a pull request for your release post. + +### Push the version + +Before you do this step, make sure the following things are done: + +- You have permission to push a new gem version to RubyGems +- You're logged into RubyGems on your command line +- A release post has been prepared, and is ideally already live +- All of the prior steps are done, committed, and pushed to `master` + +Really the only thing left to do is to run this command: + +```sh +bundle exec rake release +``` + +This will automatically build the new gem, make a release commit and tag and then push the new gem to RubyGems. Don't worry about creating a GitHub release, @jekyllbot should take care of that. + +And then, you're done! :tada: Feel free to celebrate! + +If you have access to the [@jekyllrb](https://twitter.com/jekyllrb) Twitter account, you should tweet the release post from there. If not, just ask another maintainer to do it or to give you access. + +## For non-core gems + +If you're not a maintainer for `jekyll/jekyll`, the procedure is much simpler in a lot of cases. Generally, the procedure still looks like this: + +- Bump the gem version manually, usually in `lib//version.rb` +- Adjust the history file +- Run `bundle exec rake release` or `script/release`, depending on which of the two exists +- Rejoice + +Be sure to ask your project's maintainers if you're unsure!