proposal: a version numbering scheme and release process for Go projects

proposal.md

Note to readers

Following the Go change proposal policy the following text will be the contents of the issue raised to open the discussion on this proposal.

I fully expect that this proposal will generate considerable discussion and will call for a design document. This document will be produced if the initial proposal is accepted.

---

Preface

Go projects do not have version numbers in the way it is commonly understood by our counterparts in other languages communities. This is because there is no formalised notion of releasing a Go project. There is no process of taking an arbitrary vcs commit hash and assigning it a version number that is both meaningful for humans and machines.

Additionally, Operating System distributors such as Debian and Ubuntu strongly prefer to package released versions of a project, and are currently reduced to doing things like this.

To put it another way,

Go projects are commonly tracked in vcs repositories and derive their import prefix from their vcs location. Version control systems assign revision identifiers or hashes to various copies of the source they track over time. These vcs hashes are ideal for identifying a particular copy, or revision, of a Go project. However vcs hashes are less useful at answering other types of question like:

• "Am I using the latest copy of this project ?"
• "Are there any bug fixes for version 1.5 available ?"
• "Which version of the postgres driver are compatible with this library ?"

The aim of this proposal is to establish a single recommended procedure for releasing Go projects, in the same way that gofmt defines a single recommended way to format Go source code.

Proposal

This proposal seeks to establish a recommended version numbering scheme and minimal release process for Go projects.

This process is intended to be light weight and will facilitate the creation of tools that automate the creation and consumption of released versions of Go projects.

Version numbering scheme

This proposal recommends that Go projects adopt the semantic versioning 2.0 standard for their version numbering scheme.

This recommendation is informed by the broad support for semantic versioning across our contemporaries like node.js (npm), rust (cargo), javascript (bower), and ruby (rubygems). Adherence to a commonly accepted ideal of what constitutes a major, minor, or patch release will allow Go programmers to benefit from the experiences of these other communities' dependency management ecosystems.

Tag format

Furthermore, this proposal recommends that Go projects adopt a process of releasing their software by applying a tag to their vcs repositories. The format of this tag is defined as

v<semver>

That is, the character v, U+0075, followed directly by a string which is compliant with the SemVer 2.0 standard. Tags which do not fit this format should be ignored for the purpose of determining which versions of a Go project are released.

Out of scope

The following items are out of scope, but would be addressed in a later proposals:

• How Go projects can declare the version numbers or ranges for projects they depend on.
• How go get may be changed to consume this version information.

Additionally, this proposal not seek to change the release process, or version numbering scheme for the Go (https://golang.org) distribution itself.

Replace "The following items are out of scope of, but obviously dependant on, this proposal" with something like "The following items are out of scope, but will be addressed in a later proposal." ?

@jbuberel done (ish)

This popped into my head as I turning in for the night: IMO, this initial proposal needs to be more substantial.

Proposing a convention is just an idea, not a thing. There is no manifestation of it included in this proposal. How about extending this to:

• Establishing SemVer 2.0 as the versioning standard for the Go open source ecosystem
• Exposing the cached version information via a pkgs.godoc.org endpoint to be covered in the design doc.

Without including both, you'll just have people debating SemVer. Author it in such a way that SemVer is just the obvious default, but that exposing it in a consistent way is the interesting bit.

I like the idea of adopting a consistent naming convention, Semver seems ok.

A few quick thoughts:
-- we may want a variant of the naming convention for prereleases, betas, experimentals, release candidates, etc. Perhaps a prefix on the name, or at least something different than "v". This allow us to do things like have a "release candidate" for 1.7.3, and have that be obvious in the name (rc-1.7.3)
-- Identifying incompatibility with the major digit is a good idea, but there are so many aspects to compatibility, particularly in language compilation systems: language syntax, language semantics, and endless ABI conventions. Maybe we need a better way to express some of this. Is there... consistency with earlier releases? Consistency with tools that someone somewhere may have generated for their own use? Consistency in "unspecified behavior" over time? Tricky.

That said: the Go team is so committed to compatibility between releases, one wonders if the first "1" digit is effectively unnecessary. :-) At some distant point in the future (when someone adds generics) maybe we'd have a reason to go to 2.0.0.

s/vcs/VCS/g

Is this meant to become a design doc abiding the Go change proposal process? If so, I'd like to see that skeleton in the doc, even if many of the sections are "To be discussed" or similar.

I don't see much here to object to. I agree with @jbuberel that the proposal is too light. I'd like to see some analysis of the touch points between the proposal, existing tooling, and expectations of package maintainers. It'd also be nice to see some workflows or user stories (forgive the term) to serve as motivating examples.

@tatge, I believe all of your points are addressed by SemVer 2.0 itself.

@peterbourgon @jbuberel thank you for your comments. I did not make clear, but will, that this is the text of the initial issue I intend to file to open the discussion on this proposal (see, https://github.com/golang/proposal#process). I fully expect extended debate and a call for a design document before reaching the proposal proper stage. My goal is to keep this initial issue short so as to keep the focus on the goal.

I will try to integrate your suggestions into the text of this initial issue, but my preference is to continue to keep the text as concise as possible. As always, I welcome your feedback on this approach.

@jbuberel, thank you for your comments

Proposing a convention is just an idea, not a thing. There is no manifestation of it included in this proposal. How about extending this to:

I apologise, my intention was to do in fact, the opposite. I am trying to propose a process, a set of steps, well exactly one, that are the minimum set of operations to turn active repository under development into something which downstream Go programmers can reliably consume.

Establishing SemVer 2.0 as the versioning standard for the Go open source ecosystem

You are correct that I am proposing a standard version numbering scheme, and that happens to be semver 2.0. This is for two reasons.

1. My goal here is I want a numbering scheme, so that I (and others) can write tools that can talk about versions of Go projects, not just revision numbers.
2. I chose semver 2.0 because it is a sound standard with broad support across other contemporary languages including npm (nodejs), cargo (rust), ruby. I think there is a lot of benefit from following the lead of other communities, as they do after all have a functioning dependency management ecosystem, and Go does not.

Exposing the cached version information via a pkgs.godoc.org endpoint to be covered in the design doc.

We've talked privately about a possible "package repository" that could be built once Go packages have a notion of releases and versions. I have decided to leave this out of scope for the moment, because without agreement on releasing Go projects via vcs tags, nothing else is possible.

Without including both, you'll just have people debating SemVer. Author it in such a way that SemVer is just the obvious default, but that exposing it in a consistent way is the interesting bit.

I will integrate the comments I made above into the document. Thank you for your suggestion.

👍

👍 to proposing to establish SemVer 2.0 as the versioning standard. But I'm more interested in the followup discussions on how that affects go-get and vendoring. We won't be able to popularize the idea without standard tooling support. However, gopkg.in allows us to play with SemVer today (in a less elegant way), e.g., go get gopkg.in/pkg.v1.0.0 -> github.com/go-pkg/pkg (branch/tag v1.0.0).

lgtm, we follow this process already on CoreOS projects :)