Merge pull request open-telemetry#45 from jkwatson/changelog_proposal

proposal for the CHANGELOG format specifics

docs/repository.md

@@ -19,7 +19,20 @@ Note: the **upstream** project signal you depend on (if any) MUST be stable
 ## Required Files
 
 - MUST have a [CHANGELOG.md](templates/CHANGELOG.md) updated for every release
-  - SHOULD automate population of CHANGELOG.md
+  - The CHANGELOG.md is intended to be consumed by humans, and not machines.
+  - The file SHOULD contain an `Unreleased` section at the top, which includes changes that
+  have not yet been released.
+  - The file MUST be in reverse chronological order, with the most recent
+  releases at the top of the file, after the `Unreleased` section.
+  - Each release SHOULD be separated by a line separator (`---`) from the other relases.
+  - Each release SHOULD contain separate sections for each major functionality area (if applicable).
+  The following sub-sections MAY be used, as appropriate.
+    - `General` - General comments about the release that users should know about.
+    - `Breaking Changes` - Any changes that will break backward compatibility with previous versions.
+    - `Bugfixes` - Details of bugs that were fixed.
+    - `Enhancements` - New features that have been added to the project.
+  - The CHANGELOG.md SHOULD NOT list every PR, but only changes significant from an end-user point of view. Anyone who is
+  interested in all the details of every change in the project can use the git log for that.
 - MUST add the [CODE_OF_CONDUCT.md](templates/CODE_OF_CONDUCT.md)
 - MUST add the [CONTRIBUTING.md](templates/CONTRIBUTING.md)
 - MUST have a `.github/CODEOWNERS` file with at least two currently full-time Splunkers listed

docs/templates/CHANGELOG.md

@@ -1,6 +1,39 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project are documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+The format is based on the [Splunk GDI specification](https://github.com/signalfx/gdi-specification/blob/f70eda04ec15685f892edc4b8f05bed557d20206/docs/repository.md#required-files),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### General
+
+#### Enhancements
+
+- We made everything better with this new feature.
+
+---
+
+## Version 0.1.0 - 2021-04-01
+
+### General
+
+- This release marks the first release of the project.
+
+### Functional Section 1
+
+#### Breaking changes
+
+- Unfortunately, we were forced to introduce this breaking change.
+
+#### Bugfixes
+
+- Bug 1 fixed. Here's a description of what was broken and how we fixed it.
+- Another bug we fixed goes here.
+
+### Functional Section 2
+
+#### Enhancements
+
+- Other great enhancements are written about here.