Recommendation for code versioning for OpenStax (née Connexions) code.
-
use git tags, of the form: v[numeric-version]
-
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)
- git describe at minimum
- bump versions as needed
- devops will finalize tags (and versions) at rollout
-
follow semantic versioning spec: http://semver.org a. major.minor.patch
- Major == changed external API or incompatible mode of operation
- Minor == backwards compatible changes - addition of features only
- 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.
- 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
@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?