Modularization Release Process

[stephenplusplus]

Here's the current plan regarding how to publish updates to the core gcloud module or the future @gcloud/{service} sub-modules. Thoughts very welcome!

---

An npm run script will be created to release a module:

$ npm run release [SERVICE_NAME] --major|minor|patch

Here's what happens if you wanted to publish the core gcloud module with a major update.

$ npm run release --major

# runs:
rm -rf node_modules && npm install
npm run lint
npm run test
npm run system-test
npm version major
rm -rf node_modules && npm publish
git push origin master --follow-tags

Here's what happens if you wanted to release a major update to the BigQuery API.

$ npm run release bigquery --major

# runs:
cd lib/bigquery
rm -rf node_modules && npm install
npm run lint
npm run test
npm run system-test
npm version major
rm -rf node_modules && npm publish
git push origin master --follow-tags

# Because it was a MAJOR increment (breaking changes):
npm uninstall --save @gcloud/bigquery
npm install --save @gcloud/bigquery # to depend on the new release
git commit -am 'Update @gcloud/bigquery'
npm run release [minor|major] # depending on if gcloud-node is < or > 1.0

Here's what happens if you wanted to release a patch update to the BigQuery API.

$ npm run release bigquery --patch

# runs:
cd lib/bigquery
rm -rf node_modules && npm install
npm run lint
npm run test
npm run system-test
npm version patch
rm -rf node_modules && npm publish
git push origin master --follow-tags

How about the docs?

The core package will no longer have its own JSON files. Instead, each service will have a directory in gh-pages that the core package doc pages will pull from:

$ git checkout gh-pages
$ ls
  docs
  |_ json
    |_ { existing version directories for pre-modularization JSON files }
    |_ bigquery
      |_ v0.1.0
        |_ dataset.json
        |_ index.json
        |_ job.json
        |_ table.json
        |_ types.json

How does the docs site load the correct JSON files from the modules?

Still thinking! Possible tools that can help:

• JSON.parse(http://gitnpm.com/gcloud/{$scope.activeVersion}/json/dependencies)
• The semver client-side library

[callmehiphop]

Overall I think it looks great, I only have a couple things to add in regards to the docs.

The core package will no longer have its own JSON files. Instead, each service will have a directory in gh-pages that the core package doc pages will pull from:

What about the docs in lib/index.js?

How does the docs site load the correct JSON files from the modules?

I think this should be a gcloud-common discussion? (If it isn't already)

[jgeewax]

• Could we use a term other than "release"? To some people this might mean just code changes, to others it might mean publish things to NPM. It'd be nice if it was extra clear about what's happening...
• Can we use -- syntax for the major/minor/patch since it's a modifier ? (npm run <verb> bigquery --minor)

[stephenplusplus]

Could we use a term other than "release"?

I chose it because it's all-encompassing, as opposed to just "build" or "publish", since it does both of those, and more. This is only a command that will be run by a maintainer of the library, so before they run it, they will have been told or read what it does. At its worst, if it is ambiguous, that might work in our favor in that the person running the command will check what it does. I'm open to ideas, though, if you can think of a better name.

[stephenplusplus]

Can we use -- syntax for the major/minor/patch since it's a modifier ? (npm run bigquery --minor)

Examples updated 👍

[jgeewax]

Also https://github.com/sindresorhus/np

[stephenplusplus]

We have a publish script now which handles publishing an individual module. The chain effect originally discussed here, where publishing one module triggers another, is probably a little dangerous. What we have now is working so far, so until we see need to improve, let's close this one.