From 046be12ec72448655a60dfb819b79445d1bcde02 Mon Sep 17 00:00:00 2001 From: Denis Isaev Date: Sun, 17 May 2020 22:01:57 +0300 Subject: [PATCH] docs: add versioning policy and releases --- docs/src/docs/contributing/workflow.mdx | 21 ++++++++++++++++ docs/src/docs/usage/install/index.mdx | 33 ++++++++++++++++++++++--- 2 files changed, 51 insertions(+), 3 deletions(-) diff --git a/docs/src/docs/contributing/workflow.mdx b/docs/src/docs/contributing/workflow.mdx index 99c92bb52b7e..ae0e9856e553 100644 --- a/docs/src/docs/contributing/workflow.mdx +++ b/docs/src/docs/contributing/workflow.mdx @@ -46,3 +46,24 @@ First, please, accept [CLA](https://gist.github.com/jirfag/26a39fd375da84b2d5ad4 make a comment on the pull request about it. Also, we run a few checks in CI by using GitHub actions, you can see them [here](https://github.com/golangci/golangci-lint/blob/master/.github/workflows/pr.yml). + +## New releases + +First, see [our versioning policy](/usage/install/#versioning-policy). + +To make a new release create a tag `vx.y.z`. Don't forget to add zero patch version for a new minor release, e.g. `v1.99.0`. +A GitHub action [workflow](https://github.com/golangci/golangci-lint/blob/master/.github/workflows/tag.yml) will start building and publishing release after that. + +After making a release you need to update: + +1. GitHub [action config](https://github.com/golangci/golangci-lint/blob/master/assets/github-action-config.json) by running: + +```bash +make assets/github-action-config.json +``` + +2. The latest version in documentation on our website: + +```bash +make expand_website_templates +``` diff --git a/docs/src/docs/usage/install/index.mdx b/docs/src/docs/usage/install/index.mdx index 456a26d78812..90cca8dfa864 100644 --- a/docs/src/docs/usage/install/index.mdx +++ b/docs/src/docs/usage/install/index.mdx @@ -10,7 +10,7 @@ Most installations of `golangci-lint` are performed for CI. We recommend using [our GitHub Action](https://github.com/golangci/golangci-lint-action) for running `golangci-lint` in CI for GitHub projects. It's [fast and uses smart caching](https://github.com/golangci/golangci-lint-action#performance) inside -and it can be much faster than simple binary installation. +and it can be much faster than the simple binary installation. Also, the action creates GitHub annotations for found issues: you don't need to dig into build log to see found by `golangci-lint` issues: @@ -39,8 +39,8 @@ wget -O- -nv https://raw.githubusercontent.com/golangci/golangci-lint/master/ins golangci-lint --version ``` -It is advised that you periodically update version of golangci-lint as the project is under active development -and is constantly being improved. For any problems with golangci-lint, check out recent [GitHub issues](https://github.com/golangci/golangci-lint/issues) and update if needed. +It is advised that you periodically update the version of `golangci-lint` as the project is under active development +and is constantly being improved. For any problems with `golangci-lint`, check out recent [GitHub issues](https://github.com/golangci/golangci-lint/issues) and update if needed. ## Local Installation @@ -67,6 +67,33 @@ Go source installations are supported for the two most recent Go releases. go get github.com/golangci/golangci-lint/cmd/golangci-lint@{.LatestVersion} ``` +## Versioning Policy + +`golangci-lint` follows [semantic versioning](https://semver.org). However, due to the nature of `golangci-lint` as a code quality tool, +it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy: + +- Patch release (intended to not break your lint build) + - A patch version update in a specific linter that results in `golangci-lint` reporting fewer errors. + - A bug fix to the CLI or core (packages loading, runner, postprocessors, etc). + - Improvements to documentation. + - Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage. + - Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone). +- Minor release (might break your lint build because of newly found issues) + - A major or minor version update of a specific linter that results in `golangci-lint` reporting more errors. + - A new linter is added. + - An existing configuration option or linter is deprecated. + - A new CLI command is created. + - Backward incompatible change of configuration with extremely low impact, e.g. adding validation of a list of enabled `go-critic` checkers. +- Major release (likely to break your lint build) + - Backward incompatible change of configuration with huge impact, e.g. removing excluding issues about missed comments from `golint` by default. + - A linter is removed. + +According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix). +As such, we recommend using the fixed minor version and fixed or the latest patch version to guarantee the results of your builds. + +For example, in our [GitHub Action](https://github.com/golangci/golangci-lint-action) we require users to explicitly set the minor version of `golangci-lint` +and we always use the latest patch version. + ## Next [Quick Start: how to use `golangci-lint`](/usage/quick-start).