Release Process

How to cut an OpenCoweb stable release for v1.0+.

One time setup

Follow the instructions for Developer Setup first before attempting the release steps below.

Each release

These steps are ordered such that the release on GitHub is tagged if and only if the stable packages generate without error. Stick to this order to avoid having to undo a tag.

Produce stable versions

1. Do a pull from GitHub to make sure you have all the code for the release locally.

$ git pull origin

1. Make sure the docs/changelog.rst is up-to-date with all API changes that went into the code since the last release.
2. Modify file version to reflect stable build version. Do a find and replace on the old version number and bump it to the next. WARNING: Do not blindly replace all version references. Some of them should remain at the old version (e.g., the doc changelog). BE CAREFUL! Expect files changes in: conf.py, min.'s, pom.xml, init.py, setup.py. IMPORTANT REMINDER The naming convention for should follow: version.release.modification sytnax.
3. Add changes, commit, and push to GitHub.

$ git status # see what changed
$ git commit -am "Version Stamp for Stable Build <NEXT VERSION>"
$ git push origin master

1. Do a build of the Sphinx docs and the aggregate Javadocs to make sure there are no errors.

$ cd SANDBOX_ROOT/docs
$ make html
$ make javadoc

1. Create the new JavaScript release code for the Python build.

$ cd SANDBOX_ROOT/js
$ ./setup_python_js.sh

1. Sanity Check - look for new folder using new version number

$ cd SANDBOX_ROOT/js/release/coweb-x.y

1. Create the Python source distribution.

$ cd SANDBOX_ROOT/servers/python
$ python setup.py sdist

1. Create the Maven bundles of the Java sources, binaries, and docs. Enter the GPG key password when prompted.

$ cd SANDBOX_ROOT/servers/java
$ ./bundle.sh

1. Create bundles for cowebx-dojo-widgets and coweb-boilerplate/dojo-boilerplate (if necessary). Especially if no changes went into dojo-boilerplate, there might not be any need to do this.

At this point we should really install the stable packages on an independent system and test them.

Tag the release

1. Do a final commit and push to GitHub of any outstanding changes for the release.

$ git status # see if anything changed
$ git add SOMEFILE # add all files that changed
$ git commit -m "Final build for v1.0"
$ git push origin master

1. Tag the release.

$ git tag -a v1.0

1. Push the tag to GitHub.

$ git push origin v1.0

Upload docs to opencoweb.org

1. Deploy the manual and Javadocs to opencoweb.org. (Enter the ssh password when prompted, twice.)

$ cd SANDBOX_ROOT/docs
$ make deploy

Upload Bundles to Maven Central

See this document for instructions. The bundles were generated earlier and exist in SANDBOX_ROOT/servers/java/bundles.

The bundles should be publicly visible within a few hours; it takes a little while for SonaType to update its repository.

Upload to PyPI

This process is unintuitive, not user-friendly, and seriously flawed in design. The easiest way to accomplish this is to use the distutils command line interface, since I could not even figure out how to create new releases on PyPi's online interface.

Unfortunately, the distutils interface is inconsistent and a security liability. The following instructions bypass distutils's insistence on storing username/passwords in clear-text. If you're interested in the maintainer's inability to address distutils's issue(s), read the associated bug report.

1. Create a ~/.pypirc file containing the following contents. Replace with the PyPi username. The password is intentionally left blank.

[server-login]
username:<username>
password:

1. Create the source distribution, register the new release, and upload the source all at once. Doing all three at once is the only way to not have to store the password in clear-text.

$ cd SANDBOX_ROOT/servers/python
$ python setup.py sdist register upload # Enter the PyPi password when prompted.

1. Make sure distutils didn't secretly store your password in clear-text.

$ cat ~/.pypirc

1. Double check the upload worked. Navigate to http://pypi.python.org/pypi/OpenCoweb and check the latest version. It should be the one your just uploaded...

Instead, you can try the confusing PyPi Online UI at http://pypi.python.org.

Update the demo site

Update demos.opencoweb.org to host the latest java server and cowebx-apps demos.

Bump for next release

1. Do a find and replace on the old version number and bump it to the next. WARNING: Do not blindly replace all version references. Some of them should remain at the old version (e.g., the doc changelog). BE CAREFUL! Expect files changes in: conf.py, min.'s, pom.xml, init.py, setup.py. IMPORTANT REMINDER The naming convention for should follow: version.release.modification-SNAPSHOT so that developers can differentiate between code in trunk and code in stable releases.

$ git status # see what changed
$ git add SOMEFILE # add all files that have version number changes
$ git commit -m "Version bump for <NEXT VERSION>"
$ git push origin master