Automate publishing to PyPI and gh-pages

[c-w]

This change automates the release to PyPI and gh-pages: whenever a new tag is pushed or a new release is authored in the Github UI, a new version of the project automatically gets published.

[ryan-roemer]

Nice automation work? How do we determine what semver / "next version" to release at? Or does a PR have to update the version string in __init__.py?

[c-w]

Good catch, fixed in faf6075.

[ryan-roemer]

I think I understand what's happening here now, but just to be sure, can you walk me through the lifecycle of things a human does from their computer and then after things Travis does to github and PyPI once we decide to cut a release from say current master?

Thanks!

And maybe we should have some "how to release" notes in a CONTRIBUTING.rst file or something?

[c-w]

Added the release publishing instructions in 0c2714c. Once this PR is merged, all that a human will have to do to publish a new release is to go here, name the release tag like 1.2.3, optionally give the release a name and description and then click "Publish release". This will create a tag on the repo and kick off a Travis CD build.

The CD build then does:

1. Update cloud_browser/__init__.py with the version number from TRAVIS_TAG.
2. Build the source dist package.
3. Upload the dist package to PyPI.
4. Build the sphinx docs.
5. Push the docs folder to gh-pages.

[ryan-roemer]

Thanks! That all sounds good with just one remaining question: how does the code change to cloud_browser/__init__.py get committed back to master in git?

[c-w]

The code change currently doesn't get pushed back to master. The idea here is that it's not a real code change (it's really metadata for the PyPI release) so there's no need for the exact version information to be in the source tree (it would be redundant with the PyPI release history and the git tags). I've made this more explicit in __init__.py in 98545bf.

[ryan-roemer]

It's been a while since I've attempted this, but don't we want to support git-based dependencies on this project wherein the cloud_browser/__init__.py should have a correct version entry? (That's what we always do in npm/javascript land).

Usually in JS land we do something like:

$ npm version major|minor|patch|ACTUAL_VERSION_STRING
# updates `package.json:version`, commits to git and does `git tag -a `vVERSION`

$ npm publish
# dependency available from npm as `yarn add foo@v1.2.3`

$ git push && git push --tags
# dependency available from github as `yarn add ORG/foo#v1.2.3`

Can you walk me through modern expectations in the Python community for the git master version of an __init__.py file not being in sync with PyPI?

Thanks!

[c-w]

When doing a git-based install, one would usually specify something like https://github.com/ryan-roemer/django-cloud-browser/archive/735ef1d.zip in the requirements.txt file which will fetch the project files for that SHA, run setup.py install, etc. With the changes proposed in this pull request, the project would be set up as django-cloud-browser==0.0.0 which should be fine since this is not a PyPI-published version making it explicit that this is not a normal install and the developer can still find the exact code they installed by looking at 735ef1d on Github. setup.py install doesn't really care about what is in the version string as long as there's something there (e.g. I'm using this same approach in another project and it's been working fine).

[ryan-roemer]

OK, thanks for the walkthrough and a lot of follow-on work on this PR. If that's the normal expected workflow, I'm fine with that!

I've just added one comment about reverting localdev changes if an actual human runs the publishing steps. Rest LGTM!

[c-w]

@ryan-roemer Any suggestions for what the next release's version number should be? 0.5.0?

[ryan-roemer]

0.5.0 sounds good.