Merge pull request open-telemetry#68 from signalfx/flands/versioning

Update versioning information

README.md

@@ -13,6 +13,7 @@ The following components are currently in scope:
 
 - [Configuration](docs/configuration.md)
 - [Repository](docs/repository.md)
+- [Versioning](docs/versioning.md)
 
 GDI projects MUST adopt GDI specification changes by their next minor release
 and within three months (whichever is sooner). The GDI specification and GDI

docs/repository.md

@@ -18,28 +18,43 @@ approval is granted, GDI projects MUST NOT cut a GA release.
 
 ### Permissions
 
-- MUST grant `Admin` [permission level](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization) to maintainers
-- MUST grant `Triage` [permission level](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization) to approvers
-- MUST NOT grant `Write`, `Maintain`, `Admin` [permission level](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization) to anyone else than maintainers
+- MUST grant `Admin` [permission
+  level](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization)
+  to maintainers
+- MUST grant `Triage` [permission
+  level](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization)
+  to approvers
+- MUST NOT grant `Write`, `Maintain`, `Admin` [permission
+  level](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization)
+  to anyone else than maintainers
 
 ### Branch protection
 
 - MUST have a primary branch named `main`
-- MUST NOT allow anyone (including administrators) pushing directly to `main`; **EXCEPTION:** temporarily while firefighting outstanding issues on `main` - direct push MUST be disabled as soon as the issues are resolved
+- MUST NOT allow anyone (including administrators) pushing directly to `main`;
+  **EXCEPTION:** temporarily while firefighting outstanding issues on `main` -
+  direct push MUST be disabled as soon as the issues are resolved
 - MUST require status checks to pass before merge to `main`
 - MUST require at least one CODEOWNER to approve a PR prior to merge
 - MUST require signed commits on `main`
 - MUST allow ONLY squash or rebase merging
 
 ### Dependencies
 
-- MUST lock the versions of all build dependencies (e.g. libraries, binaries, scripts, docker images) or vendor them; **EXCEPTION:** tools that are available out-of-the-box
+- MUST lock the versions of all build dependencies (e.g. libraries, binaries,
+  scripts, docker images) or vendor them; **EXCEPTION:** tools that are
+  available out-of-the-box
 - MUST have Dependabot configured
 
 ### GitHub Actions
 
-- MUST use [GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets) to store sensitive data (auth tokens, passwords) and limit their usage to only required places
-- MUST NOT use [Personal Access Tokens](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) in GitHub Actions
+- MUST use [GitHub
+  secrets](https://docs.github.com/en/actions/reference/encrypted-secrets) to
+  store sensitive data (auth tokens, passwords) and limit their usage to only
+  required places
+- MUST NOT use [Personal Access
+  Tokens](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)
+  in GitHub Actions
 - MUST [limit permissions of `GITHUB_TOKEN`](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token) when used
   - MUST only set the absolutely required `permissions` (least privilege)
   - MUST set `permissions` for individual `jobs`
@@ -93,6 +108,7 @@ Note: the **upstream** project signal you depend on (if any) MUST be stable
 - MUST have a signature or a checksum with signature for all release artifacts
   - SHOULD use Splunk signing key
 - MUST use [signed tags](https://docs.github.com/en/github/authenticating-to-github/signing-tags)
+- MUST state version of OpenTelemetry components built against if applicable
 
 ## Collector
 

docs/versioning.md

@@ -1,17 +1,28 @@
 # Versioning
 
+All GDI projects MUST be versioned according to [Semantic Versioning
+2.0](https://semver.org/spec/v2.0.0.html). GDI projects are versioned
+separately from OpenTelemetry components as Splunk-specific breaking changes
+MAY be introduced. GDI projects MUST indicate what version of OpenTelemetry
+components they are based on through release notes and SHOULD indicate through
+logging. Additional version number constraints can be found in the sections
+below.
+
 ## Experimental
 
 Everything in the specification starts as experimental, which covers alpha,
-beta, and release candidate versions. While any component in the specification
-is experimental, breaking changes and performance issues MAY occur. Components
-SHOULD NOT be expected to be feature-complete. In some cases, the experiment
-MAY be discarded and removed entirely. Long-term dependencies SHOULD NOT be
-taken against experimental components.
+beta, and release candidate versions. Version numbers for releases MUST be less
+than `1.0.0` while experimental. The minor version number SHOULD be increased
+when significant or breaking changes are introduced.
+
+While any component in the specification is experimental, breaking changes and
+performance issues MAY occur. Components SHOULD NOT be expected to be
+feature-complete. In some cases, the experiment MAY be discarded and removed
+entirely. Long-term dependencies SHOULD NOT be taken against experimental
+components.
 
 GDI projects MUST be designed in a manner that allows experimental components
 to be created without breaking the stability guarantees of existing components.
-
 GDI projects MUST NOT be designed in a manner that breaks existing users when a
 new component beyond the project's first component transitions from
 experimental to stable. This would punish users of the release candidate
@@ -26,7 +37,8 @@ and experimental projects.
 
 Once an experimental component has gone through rigorous beta testing, it MAY
 transition to stable. Long-term dependencies MAY now be taken against this
-component.
+component. The initial stable release version number MUST be `1.0.0` and follow
+Semantic Versioning 2.0 for all subsequent releases.
 
 All components MAY become stable together, or MAY transition to
 stability component-by-component.