mirror of
https://github.com/coder/coder.git
synced 2025-07-12 00:14:10 +00:00
445392bdd8
Adds some package-level documentation to reduce confusion on when it is appropriate or warranted to bump apiversions.
27 lines
1.3 KiB
Go
27 lines
1.3 KiB
Go
// Package apiversion provides an API version type that can be used to validate
|
|
// compatibility between two API versions.
|
|
//
|
|
// NOTE: API VERSIONS ARE NOT SEMANTIC VERSIONS.
|
|
//
|
|
// API versions are represented as major.minor where major and minor are both
|
|
// positive integers.
|
|
//
|
|
// API versions are not directly tied to a specific release of the software.
|
|
// Instead, they are used to represent the capabilities of the server. For
|
|
// example, a server that supports API version 1.2 should be able to handle
|
|
// requests from clients that support API version 1.0, 1.1, or 1.2.
|
|
// However, a server that supports API version 2.0 is not required to handle
|
|
// requests from clients that support API version 1.x.
|
|
// Clients may need to negotiate with the server to determine the highest
|
|
// supported API version.
|
|
//
|
|
// When making a change to the API, use the following rules to determine the
|
|
// next API version:
|
|
// 1. If the change is backward-compatible, increment the minor version.
|
|
// Examples of backward-compatible changes include adding new fields to
|
|
// a response or adding new endpoints.
|
|
// 2. If the change is not backward-compatible, increment the major version.
|
|
// Examples of non-backward-compatible changes include removing or renaming
|
|
// fields.
|
|
package apiversion
|