Skip to content

SDK Update Practices

Jump to bottom
Josh Gavant edited this page Mar 27, 2018 · 1 revision

SDK Update Practices

The Azure SDK for Go tries to serve Go developers by making it easier to use Azure's APIs in Go apps. As part of that service and because users need to learn about API changes to properly update their code, we signal SDK updates through semantically meaningful version numbers - semantic versioning. Those version numbers are applied to this git repo as tags per Go's requirements.

For better and worse, though, Azure's large surface means its interfaces change frequently, and some of these changes require new major versions of supporting packages per semver guidelines. Go relies on git tags for marking versions and a single repo has only one set of tags, so when even one package requires a major revision we have to bump the version of the entire repo. These factors combined have led us to release new major versions of the SDK almost once per month.

Some users have asked us to reduce the frequency of major revisions so that our updates are more predictable and less likely to require code changes, a reasonable request :). To that end our team has discussed several alternatives, including breaking the repo into many smaller repos, relying on a redirect service and artificial version paths a la gopkg.in, or even abandoning semver altogether.

After consideration, though, we believe developers appreciate the convenience of a single repo and also prefer semver versioning even if it leads to high version numbers. To nevertheless meet the need for more stability and predictability, we are adopting the following repo structure and release cadence while continuing to follow semver. Please share your feedback and suggestions with us in issues, thanks!

latest and master branches

We provide two main branches in this repo: latest and master.

  • latest offers bindings for the very latest Azure APIs and is automatically updated as soon as specifications are added or changed no matter what breaking changes are introduced. In this branch no version tags are used so users will get changes whenever they update; that is, there is no versioning.

  • master on the other hand offers versioning and a bit more stability by including version tags which follow semver guidelines. This branch will only receive minor updates at most times; but at the end of each month, major changes will be backported from latest to master and master will be tagged with a new major version. That is, at these times latest and master will converge.

NOTE: APIs under services/preview are in version zero and should always be considered unstable.

New major versions from the master branch will be released at the end of each month with a complete changelog and a notice in the Azure Updates feed.

How to use

To choose a branch or version, specify it in your dependency management manifest (e.g. Gopkg.toml, Glide.yaml, etc.) as follows.

dep

In the [[constraint]] section for a package, specify one of the following. The comment indicates the results of afterwards running dep ensure -update for that package.

branch = "latest"     // get latest commit from `latest` branch
branch = "master"     // get latest commit from `master` branch
version = "v14.5.0"   // get tagged commit from `master` branch

glide

Specify your target branch or version number in the version field as follows, then run glide up.

- package: github.com/Azure/azure-sdk-for-go
  version: [ latest | master | X.Y.Z ]
Clone this wiki locally