Versioning and Branches

Scaled-down Semantic Versioning

Semantic versioning is great, but with the huge surface area of the dc.js API and the interconnection of many of its features, we don't want to bump the major version every time the interface has breaking changes.

So dc.js follows "scaled-down semantic versioning", where

• the major version indicates a long-term strategy or architecture
• the minor version indicates a different interface (JS or CSS) or significantly different behavior
• the patch version indicates a release with backward-compatible features or bug fixes

Of course, a strong effort will be made to preserve backward compatibility even with minor and major version changes, but there are often cases when the previous interface was wrong, and preserving readability of the code is also a goal.

Development Branches

Currently:

• 3.0.* is the version supporting D3v4/5
• 2.2.* is the version supporting D3v3. New features will only be back-ported by special request.

dc.js uses git flow for orderly branch management. This blog post is an excellent introduction.

Unstable work which is not ready for release happens on the develop branch, and master always represents a released version (occasionally with inconsequential changes such as new examples or documentation changes). The GitHub Pages site http://dc-js.github.io/dc.js/ is always published from master.

Feature branches (and most PRs) are branched off develop. We're not consistent about naming them feature/* but it's pretty safe to assume that any long-life branch that sounds like a feature, is a feature branch. Features and PRs often get rebased and sometimes squashed before merging to develop or a hotfix, so don't be surprised if your contribution results in less commits than you submitted.

The essence of git-flow is that branches are cleanly mergeable into each other, and cherry-picking is not usually necessary. Per git-flow, hotfix branches are branched off master; when the hotfix is finished, it gets merged to master, that gets tagged, and the hotfix also gets merged into develop. Release branches are branched off develop; when they are finished they are merged to master. (This allows the next version to be started on develop before the release is finished.) Read the above links for a more thorough introduction to git-flow.

dc.js supports old versions using support branches, e.g. support/2.x. This is how we continue to maintain the stable release while doing most work in the unstable version. Usually this works like a hotfix², i.e. the changes get merged to the support branch, which is tagged and released, and then the changes go to a regular hotfix branch which is merged to master (and tagged) and develop.