Code Versioning for OpenStax CNX

gistfile1.md

Recommendation for code versioning for OpenStax (née Connexions) code.

1. use git tags, of the form: v[numeric-version]

2. we tag complete (or at least, stable) features, for roll out to demo, qa, sprint and production a. exception: dev will roll from HEAD of master b. tags will be on the master branch, post merge (if other patchfix tags are needed, devops will tag on staging/production) c. Tags are done by developers, primarily, and include "in development" extra version info (see below)

   1. git describe at minimum
   2. bump versions as needed
   3. devops will finalize tags (and versions) at rollout

3. follow semantic versioning spec: http://semver.org a. major.minor.patch

   1. Major == changed external API or incompatible mode of operation
   2. Minor == backwards compatible changes - addition of features only
   3. Patch == no compatibility issues - bug fix only

c. exception/extension - use item 10. "build metadata" as "post release" (under discussion, may use git describe format) 1. e.g. 1.3.4+4-45er455 2. make sure they lexically sort - we may or may not use uuids, perhaps short feature names? 3. semver/semver#200

d. Consequences - 1. All currently released code should already be > 1.0 2. Change of API (authoring <-> webview, authoring <-> publish, etc.) needs a major version bump, unless coded so as to be backward compatible - i.e. new info in /extras, webview ignores, also, webview looks for new info, but doesn't break if not present. 3. I will assume patch-level changes (and minor level changes) can be safely rolled out w/o concerns about compatibility - minor changes will need all parts for feature to be active, however.

4. Declare dependencies using versions a. Within a code base (python; javascript; ruby; less) use existing build tools to declare dependencies b. Between code bases (across an API: e.g. webview <-> archive) document dependencies in README, Install, and Changelog, as appropriate

As I mentioned in our previous discussion, I think tagging should take place anytime you want the code on a cnx server. This would differ from "we tag when necessary, when features are complete - typically end of sprint."

Using the tag to release onto server approach should provide a degree of checks before tapping someone's shoulder about updating. Also, github tags can be watched, so a development server could watch for tag and update automatically. This may then lead into the ability to (pip) freeze the development environment, for replication on a staging server.

@pumazi agreed. That point was fuzzy, and one that Ed picked on as well. I think I came to the same conclusion, modulo one diff: dev server will be updated from HEAD of master. I like the idea of watching tags. Can you expand on that? Is it a git-hook thing?

@reedstrm Yes, it would be a webhook. We would have some small service listen for the incoming events, which would git pull and restart the services.

I'm concerned about using such a hook if there are non-automated upgrade steps needed. Perhaps the hook would need to be smart enough to parts the version # and only auto-up on min/patch level changes?