New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add document on releasing a new version #6745

Merged
merged 11 commits into from Feb 7, 2018

Conversation

Projects
None yet
6 participants
@oe
Member

oe commented Feb 4, 2018

Closes #6721

oe added some commits Feb 4, 2018

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

This comment has been minimized.

@DirtyF

DirtyF Feb 4, 2018

Member

A shorter overview of the release process

  1. Update manually lib/jekyll/version.rb and bump version according to SemVer (e.g, 3.8.0)
  2. Update manually History.markdown and replace current HEAD
  3. Run bundle exec rake site:releases:new[3.8.0] and write release post (submit the post to other maintainers review). Thanks and mention all collaborators since latest version with git shortlog -sn master...v3.7.2
  4. Run bundle exec rake site:generate to update docs/latest_version.txt, docs/_config.yml and generate History page.
  5. git add . && git commit -m "Release :gem: v3.8.0".
  6. bundle exec rake release
  7. Tweet and celebrate 🎉

This comment has been minimized.

@oe

oe Feb 5, 2018

Member

@DirtyF Done!

This comment has been minimized.

@DirtyF

DirtyF Feb 5, 2018

Member

What about the 4th point?

This comment has been minimized.

@oe

oe Feb 5, 2018

Member

oh whoops, forgot about changing the command there

oe added some commits Feb 5, 2018

@ashmaroli

Looks good.. except for these very minor nits.. 👍

+## 3.7.1 / 2018-01-25
```
Adjust the version number and the date. Don't worry about removing the `HEAD` part, it'll automatically be regenerated when the time comes.

This comment has been minimized.

@ashmaroli

ashmaroli Feb 5, 2018

Member
- it'll automatically be
+ it'll be automatically
## Write a release post
In case this isn't done already, you can generate a new release post using the include `rake` command:

This comment has been minimized.

@ashmaroli

ashmaroli Feb 5, 2018

Member
- using the include `rake` command:
+ using the included `rake` command:

Concerns addressed..

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

This comment has been minimized.

@DirtyF

DirtyF Feb 5, 2018

Member

For the plugins under the jekyll org, the workflow should be almost the same :

  1. Bump version manually, in lib/jekyll-plugin-name/version.rb
  2. Adjust History file with new version and current date
  3. Commit your changes with a "Release 💎 v1.2.3" message
  4. bundle exec rake release (build, tag, push the gem and trigger a release on GitHub)

Some plugins have a script/release that runs script/cibuild before releasing a gem.

# 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. Like at 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 at a job, you should probably take a break from Jekyll at least a few times a year.

This comment has been minimized.

@pathawks

pathawks Feb 6, 2018

Member

Maybe “Like with a job” instead of “at?”

This comment has been minimized.

@DirtyF

DirtyF Feb 6, 2018

Member

Maybe we could avoid repeat this 3 times in a single paragraph?

@@ -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 `+` is optional.

This comment has been minimized.

@pathawks

pathawks Feb 6, 2018

Member

Really‽ TIL

This comment has been minimized.

@DirtyF

This comment has been minimized.

@pathawks

pathawks Feb 6, 2018

Member
  1. That is AWESOME!
  2. From that line, it appears that the + is not optional for the label to be respected. @parkr?

This comment has been minimized.

@DirtyF

DirtyF Feb 6, 2018

Member

@oe is right it works without the +, I just saw that in #6750

This comment has been minimized.

@DirtyF

DirtyF Feb 6, 2018

Member

Expect to see a lot more :shipit: in future PRs :)

This comment has been minimized.

@pathawks

pathawks Feb 7, 2018

Member

#6750 Was merged without being placed in the docs section. The + is not optional.

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 (features, enhancements) which necessitate a minor version bump (v3.1 ~> v3.2)

This comment has been minimized.

@pathawks

pathawks Feb 6, 2018

Member

I think feature and enhancement refers specifically to the labels, and need not be pluralized.

+## 3.7.1 / 2018-01-25
```
Adjust the version number and the date. Don't worry about removing the `HEAD` part, it'll be regenerated when the time comes.

This comment has been minimized.

@pathawks

pathawks Feb 6, 2018

Member

“Don’t worry about removing the HEAD part” makes me think I should not remove that line, whichever is not the case.

This comment has been minimized.

@oe

oe Feb 6, 2018

Member

Yeah, that's badly worded.

oe added some commits Feb 6, 2018

@@ -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 `+` is optional.

This comment has been minimized.

@pathawks

pathawks Feb 7, 2018

Member

#6750 Was merged without being placed in the docs section. The + is not optional.

@pathawks

This comment has been minimized.

Member

pathawks commented Feb 7, 2018

1706544

The PR was successfully merged, but was not placed under the docs header. The + is not optional.

@oe

This comment has been minimized.

Member

oe commented Feb 7, 2018

@pathawks Ah, okay. Was curious about that, good to know.

@pathawks

🍻🦋

@oe

This comment has been minimized.

Member

oe commented Feb 7, 2018

@jekyllbot: merge +docs

@jekyllbot jekyllbot merged commit 4c9166a into master Feb 7, 2018

3 checks passed

WIP ready for review
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@jekyllbot jekyllbot deleted the docs/releasing-version branch Feb 7, 2018

@parkr

This is terrific! Thank you. A little late to the game but made some comments for your consideration. Feel free to ignore!

## Write a release post
In case this isn't done already, you can generate a new release post using the included `rake` command:

This comment has been minimized.

@parkr

parkr Feb 7, 2018

Member

This should be done ahead of time in a pull request, ideally.

- 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

This comment has been minimized.

@parkr

parkr Feb 7, 2018

Member

We should make sure the release post is merged in so that the bundled site in jekyll-docs sees the release post.

- 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`

This comment has been minimized.

@parkr

parkr Feb 7, 2018

Member

I find it best to let bundle exec rake release do the final committing.

I edit History.markdown, lib/jekyll/version.rb, then git add those files to stage them. Then I run rake release, which commits them like so: 848bd4e. It's not necessary, but it makes semantic sense (commit message says "release" and you can see the version change in version.rb and in History.markdown)

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/<plugin_name>/version.rb`

This comment has been minimized.

@parkr

parkr Feb 7, 2018

Member

sometimes in the gemspec

This comment has been minimized.

@DirtyF

DirtyF Feb 7, 2018

Member

I tried to normalize the bevaviour for the plugins in Jekyll Organization 😓

- Bump the gem version manually, usually in `lib/<plugin_name>/version.rb`
- Adjust the history file
- Run `bundle exec rake release` or `script/release`, depending on which of the two exists

This comment has been minimized.

@parkr

parkr Feb 7, 2018

Member

git add the history file and the file which has the version bump too

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment