chore(apiversion): add guidelines regarding bumping apiversion (coder#16009)

Adds some package-level documentation to reduce confusion on when it is
appropriate or warranted to bump apiversions.

Author: johnstcn

apiversion/doc.go

@@ -0,0 +1,26 @@
+// 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