Change Management

[NicholasBoll]

Intro

Canvas Kit follows Semantic Versioning.

Canvas Kit supports 2 major versions at any given time. The support branch represents the previous major version while master represents the current major version. Only bug fixes can go into the support or master branches. All commits from support and master are automatically released as patches to npmjs.com. The prerelease/minor branch should contain only new features that do not break any existing functionality and will be merged into master on no less than a three-week cadence. The prerelease/major branch represents the next major version and can contain breaking changes.

Forward Merging

Forward merging is defined as a commit should exist in the history of every branch downstream. The following shows the forward merge strategy for the four branches in Canvas Kit:

support -> master -> prerelase/minor -> prerelease/major

This means prerelease/major should contain all the commits in every branch. prerelease/minor should contain all the commits in master and support.

Canvas Kit tries to make it easy to track bugs and bug fixes as well as features. A bug should be fixed in the lowest support version possible and allowed to forward merge. This ensures a commit hash can be accurately tracked for which versions it is in. For example, if a bug is fixed in the support branch, that commit will be forward-merged into master. If we want to find out which versions some commit belongs to, we can look at the commit in GitHub.com and it will list out all the tags that commit belongs to. The alternative is using a cherry-pick, but that will create a new commit hash and inspecting a commit will not accurately inform you which versions should contain a fix.

To ensure we can easily identify fixes with fixed versions, you should always choose to fix a bug in the lowest branch that bug can be found in. For example, if a bug exists in both the support branch and the master branch, the support branch should be chosen as the base branch for the pull request. This should apply even if master has diverged from support, causing a merge conflict. The forward-merge process tries to automatically test forward-merges and will merge if everything passes and create a pull request if it fails (including merge conflicts). The pull request automation will add the authors to the reviewer list of any commit being forward-merged. It should be up to the author of the original commit to semantically apply the fix to master so that the bug is effectively fixed in both support and master in a way that makes sense for each branch respectively. This ensures we can track bugs semantically rather than code-line matches.

SLA

Semantic versioning states patch and minor releases should not break existing functionality. We'd like to offer a guarantee that intended functionality will not break if an application updates to use a new patch or minor. Ideally, we'd like users of Canvas Kit to be able to have a system-provided version of Canvas Kit. This means if your application needs Canvas Kit version 12, you may automatically get the latest version of v12 (i.e. 12.0.0, 12.0,1, 12.1.0, etc) without the application breaking. This guarantee will allow teams to use a global instance of Canvas Kit rather than bundling their own version of Canvas Kit with their own bundle. This will decrease bandwidth and CPU processing time in the cases where there are multiple bundles of applications on a page at the same time.

This only applies to "main": @workday/canvas-kit-react and @workday/canvas-kit-css. The preview and labs packages of either React or CSS do not offer this guarantee and therefore should be bundled and not offered globally.

Patch releases

A patch release should contain only fixes to broken code and not break existing functionality. This statement can be subjective as any change could break someone's expectation of behavior. In general, a patch should follow this process:

• write a specification verifying previous behavior fails (bug)
• update code to pass new specification
• no other specifications should fail

If a behavior change makes other tests fail, that may be an indication that the change may break realistic expectations of existing functionality in a way that may break and application using Canvas Kit. Other tests failing isn't necessarily a blocker, but may indicate this bug fix isn't safe to apply. It may be impossible to determine if a change breaks every downstream user, especially if a downstream use is in a private repository, but the Canvas Kit team should at least look at internal applications to determine if a change will break existing functionality.

Minor releases

The same checks apply as patch releases. Ideally a minor release contains only opt-in functionality:

• new props, functions, components
• At @deprecate to props or components that are replaced by new components. This should give users a notice that there's a better option available to make major release changes less

Major releases

Functionality is allowed to break in major releases.