From 7f5ca490f60359a3ed67954e596426d37dcf8c52 Mon Sep 17 00:00:00 2001 From: Will Norris Date: Wed, 1 Nov 2017 21:20:59 +0000 Subject: [PATCH 1/4] readme: add section on versioning --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index f416c81db7d..a33f362b426 100644 --- a/README.md +++ b/README.md @@ -238,6 +238,30 @@ straightforward. [roadmap]: https://docs.google.com/spreadsheet/ccc?key=0ApoVX4GOiXr-dGNKN1pObFh6ek1DR2FKUjBNZ1FmaEE&usp=sharing [contributing]: CONTRIBUTING.md +## Versioning ## + +In general, go-github follows [semver](http://semver.org/) as closely as we can +for tagging releases of the package. For self-contained libraries, the +application of semantic versioning is relatively straightforward and generally +understood. But because go-github is a client library for the GitHub API, +which itself changes behavior, and because we are typically pretty aggressive +about implementing preview features of the GitHub API, we've adopted the +following versioning policy: + +* We increment the **major version** with any incompatible change to + non-preview functionality, including changes to the exported Go API surface + or behavior of the API. +* We increment the **minor version** with any backwards-compatible changes to + functionality, as well as any changes to preview functionality in the GitHub + API. GitHub makes no guarantee about the stability of preview functionality, + so neither do we consider it a stable part of the go-github API. +* We increment the **patch version** with any backwards-compatible bug fixes. + +Preview functionality may take the form of entire methods or simply additional +data returned from an otherwise non-preview method. We do our best to call out +which portions of a method's behavior and/or data are part of a GitHub Preview +in the appropriate Go doc. + ## License ## This library is distributed under the BSD-style license found in the [LICENSE](./LICENSE) From 7dab1e13afc522348ed43e88164c006fde4fbb19 Mon Sep 17 00:00:00 2001 From: Will Norris Date: Tue, 30 Jan 2018 17:52:47 +0000 Subject: [PATCH 2/4] refer to GitHub API docs for preview details also fix whitespace between sentences --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a33f362b426..17077d74f04 100644 --- a/README.md +++ b/README.md @@ -243,7 +243,7 @@ straightforward. In general, go-github follows [semver](http://semver.org/) as closely as we can for tagging releases of the package. For self-contained libraries, the application of semantic versioning is relatively straightforward and generally -understood. But because go-github is a client library for the GitHub API, +understood. But because go-github is a client library for the GitHub API, which itself changes behavior, and because we are typically pretty aggressive about implementing preview features of the GitHub API, we've adopted the following versioning policy: @@ -258,9 +258,8 @@ following versioning policy: * We increment the **patch version** with any backwards-compatible bug fixes. Preview functionality may take the form of entire methods or simply additional -data returned from an otherwise non-preview method. We do our best to call out -which portions of a method's behavior and/or data are part of a GitHub Preview -in the appropriate Go doc. +data returned from an otherwise non-preview method. Refer to the GitHub API +documentation for details on preview functionality. ## License ## From 9046bc024ec14602b64c6e60210ed8c700f7602a Mon Sep 17 00:00:00 2001 From: Will Norris Date: Tue, 30 Jan 2018 17:55:35 +0000 Subject: [PATCH 3/4] drop libraryVersion in favor of semantic versioning --- github/github.go | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/github/github.go b/github/github.go index 082472260b1..f3eadce9e97 100644 --- a/github/github.go +++ b/github/github.go @@ -27,10 +27,9 @@ import ( ) const ( - libraryVersion = "15" defaultBaseURL = "https://api.github.com/" uploadBaseURL = "https://uploads.github.com/" - userAgent = "go-github/" + libraryVersion + userAgent = "go-github" headerRateLimit = "X-RateLimit-Limit" headerRateRemaining = "X-RateLimit-Remaining" From db36a73a45043302699dca3a2b408bb2b7024e0a Mon Sep 17 00:00:00 2001 From: Will Norris Date: Tue, 30 Jan 2018 18:05:57 +0000 Subject: [PATCH 4/4] use https for semver.org URL --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 17077d74f04..70ae22999b8 100644 --- a/README.md +++ b/README.md @@ -240,13 +240,13 @@ straightforward. ## Versioning ## -In general, go-github follows [semver](http://semver.org/) as closely as we can -for tagging releases of the package. For self-contained libraries, the +In general, go-github follows [semver](https://semver.org/) as closely as we +can for tagging releases of the package. For self-contained libraries, the application of semantic versioning is relatively straightforward and generally -understood. But because go-github is a client library for the GitHub API, -which itself changes behavior, and because we are typically pretty aggressive -about implementing preview features of the GitHub API, we've adopted the -following versioning policy: +understood. But because go-github is a client library for the GitHub API, which +itself changes behavior, and because we are typically pretty aggressive about +implementing preview features of the GitHub API, we've adopted the following +versioning policy: * We increment the **major version** with any incompatible change to non-preview functionality, including changes to the exported Go API surface