Skip to content

Commit

Permalink
docs(COLLABORATOR_GUIDE): how to release Video.js (#4586)
Browse files Browse the repository at this point in the history
  • Loading branch information
gkatsev authored Aug 30, 2017
1 parent 6e2a302 commit 9588602
Show file tree
Hide file tree
Showing 2 changed files with 142 additions and 457 deletions.
157 changes: 142 additions & 15 deletions COLLABORATOR_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -259,23 +259,16 @@ git reset --hard upstream/master
## video.js releases
Releasing video.js is partially automated through [`conrib.json`](/contrib.json) scripts. To do a release, you need a couple of things: npm access, GitHub personal access token.
Releasing video.js is partially automated through various scripts.
To do a release, you need a couple of things: npm access, GitHub personal access token.
Releases in video.js are done on npm and GitHub and eventually posted on the CDN. These
are the instructions for the npm/GitHub releases.
Releases in video.js are done on npm and GitHub and eventually posted on the CDN.
These are the instructions for the npm/GitHub releases.
When we do a release, we release it as a `next` tag on npm first and then at least a week later, we promote this release to `latest` on npm.
### Getting dependencies
#### Install contrib
You can install it globally
```sh
npm i -g contrib/contrib
```
#### npm access
To see who currently has access run this:
Expand All @@ -285,30 +278,154 @@ npm owner ls video.js
```
If you are a core committer, you can request access to npm from one of the current owners.
Access is managed via an [npm organization][npm org] for [Video.js][vjs npm].
#### GitHub personal access token
This is used to make a GitHub release on videojs. You can get a token from the [personal access tokens](https://github.com/settings/tokens) page.
After generating one, make sure to keep it safe because GitHub will not show the token for you again. A good place to save it is Lastpass Secure Notes.
### Deciding what type of version release
Since we follow the [conventional changelog conventions][conventions],
all commits are prepended with a type, most commonly `feat` and `fix`.
If all the commits are fix or other types such as `test` or `chore`, then the release will be a `patch` release.
If there's even one `feat`, the release will be a `minor` release.
If any commit has a `BREAKING CHANGE` footer, then the release will be a `major` release.
Most common releases will be either `patch` or `minor`.
### Doing a release
To do a release, check out the master branch
It is also recommended you have a clean clone of Video.js for each release line you want to release.
That means having a folder for master/v6 and one for 5.x.
This is because 5.x and 6.x have different versions expecations for release process and have different dependencies.
Plus, during development you could end up with a dirty repo, so, it just usually easier if you have a clean release repo.
```sh
# for v6
git clone [email protected]:videojs/video.js.git videojs-6-release
# for v5
git clone [email protected]:videojs/video.js.git videojs-5-release
```
#### Video.js 6
Make sure go to the master branch and grab the latest updates.
```sh
git checkout master
git pull origin master
```
Then run the contrib command to do the next release. Don't forget to provide your GitHub token so the GitHub release goes through.
At this point, you should run `npm install` because dependencies may have changed.
Then, it's mostly a standard npm package release process with running `npm version`, followed by an `npm publish`.
```sh
VJS_GITHUB_USER=gkatsev VJS_GITHUB_TOKEN=my-personal-access-token contrib release next patch
npm version {major|minor|patch}
```
This makes a patch release, you can also do a `minor` and a `major` release.
Depending on the commits that have been merged, you can choose from `major`, `minor`, or `patch` as the versioning values.
See [deciding what type of version release section](#deciding-what-type-of-version-release).
Optionally, you can run `git show` now to verify that the version update and CHANGELOG automation worked as expected.
Afterwards, you want to push the commit and the tag to the repo.
It's necessary to do this before running `npm publish` because our GitHub release automation
relies on the commit being available on GitHub.
```sh
git push --tags origin master
```
Finally, run `npm publish` with an appropriate tag. Don't forget to supply your token.
```sh
VJS_GITHUB_USER=gkatsev VJS_GITHUB_TOKEN=my-personal-access-token npm publish --tag next
```
After it's done, verify that the GitHub release has the correct changelog output.
This is to make sure that the CHANGELOG didn't get garbled and isn't missing pieces.
If the GitHub release did not work correctly, such as if the GitHub token was not provided,
you can run it manually:
```sh
VJS_GITHUB_USER=gkatsev VJS_GITHUB_TOKEN=123 node build/gh-release.js --prelease
```
#### Video.js 5
Make sure to go to the 5.x branch and grab the latest updates.
```sh
git checkout 5.x
git pull origin 5.x
```
> *Note:* you probably need to delete v6 tags due to the way that the our CHANGELOG lib works.
>
> You can run this to delete them:
> ```sh
> git tag | grep '^v6' | xargs git tag -d
> ```
> This will find all tags that start with `^v6` and delete them.
At this point, you should run `npm install` because dependencies may have changed.
Then, we have a script that automates most of the steps for publishing. It's a little trickier than publishing v6.
##### Edit git-semver-tags
You'll need to edit `git-semver-tags` to support our usage of tags that are not part of the branch.
In the file `node_modules/conventional-changelog-cli/node_modules/conventional-changelog/node_modules/conventional-changelog-core/node_modules/git-semver-tags/index.js`, edit the line that says sets the `cmd` to be:
```js
var cmd = 'git log --all --date-order --decorate --no-color';
```
#### And now for the release
After getting rid of the tags and getting the latest updates, you can just run the release script:
```sh
VJS_GITHUB_USER=gkatsev VJS_GITHUB_TOKEN=123 ./build/bin/release-next.sh
```
It will prompt you for a version change type, so, input `patch` or `minor` or `major`.
See [deciding what type of version release section](#deciding-what-type-of-version-release).
When it's done building everything, it'll show you the commit that's made via the default pager (i.e., less).
At this point you can verify that things look normal rather than, for example, missing all the CSS.
After exiting the pager, it'll make sure you want to continue with publishing.
It will automatically release it as a `next-5` tag on npm.
Then push the local changes up:
```sh
git push --tags origin 5.x
```
Also, you'll need to copy the CHANGELOG for this version and manually edit the GitHub release to include it.
The current release's CHANGELOG could be copied from the [raw CHANGELOG.md file][raw chg] (or locally from the markdown file)
and then pasted into the correct [GitHub release](https://github.com/videojs/video.js/releases).
### Deploy as a patch to the CDN
Follow the steps on the [CDN repo][] for the CDN release process.
If it's a `next` or `next-5` release, only publish the patch version to the CDN.
When the version gets promoted to `latest` or `latest-5`, the corresponding `minor` or `latest` version should be published to the CDN.
### Announcement
An announcement should automatically make it's way to #announcements channel on [slack][], it uses IFTTT and might take a while.
You can also post it to twitter or ask someone (like @gkatsev) to post on your behalf.
If it's a large enough release, consider writing a blog post as well.
## Doc credit
Expand All @@ -319,3 +436,13 @@ This collaborator guide was heavily inspired by [node.js's guide](https://github
[pr template]: /.github/PULL_REQUEST_TEMPLATE.md
[conventions]: https://github.com/videojs/conventional-changelog-videojs/blob/master/convention.md
[vjs npm]: http://npmjs.com/org/videojs
[npm org]: https://docs.npmjs.com/misc/orgs
[slack]: http://slack.videojs.com
[CDN repo]: https://github.com/videojs/cdn
[raw chg]: https://raw.githubusercontent.com/videojs/video.js/5.x/CHANGELOG.md
Loading

0 comments on commit 9588602

Please sign in to comment.