From 2ded691f9d35ac142aa2c6da01fc0f5884398365 Mon Sep 17 00:00:00 2001
From: Josh Suereth <joshuasuereth@google.com>
Date: Fri, 28 Jul 2023 08:26:16 -0400
Subject: [PATCH] Update contributing documentation for restructuring of
 repository (#216)

Co-authored-by: Johannes Tax <johannes@johannes.tax>
Co-authored-by: Armin Ruech <armin.ruech@dynatrace.com>
---
 CONTRIBUTING.md | 47 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 44 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bc249e082..5721670ff 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,10 +11,51 @@ requirements and recommendations.
 Before you can contribute, you will need to sign the [Contributor License
 Agreement](https://identity.linuxfoundation.org/projects/cncf).
 
-## TODO
+## How to Contribute
 
-We need to flesh out the rest of the contributing document for specifics on
-semantic conventions.
+When contributing to semantic conventions, it's important to understand a few
+key, but non-obvious, aspects:
+
+- All attributes, metrics, etc. are formally defined in YAML files under
+  the `model/` directory.
+- All descriptions, normative language are defined in the `docs/`
+  directory.
+  - We provide tooling to generate Markdown documentation from the formal
+    YAML definitons.  See [Yaml to Markdown](#yaml-to-markdown).
+  - We use Hugo to render [semantic conventions on our website](https://opentelemetry.io/docs/specs/semconv/).
+    You will see `<!--- Hugo front matter used to generate ...` sections
+    in markdown.  See [Hugo frontmatter](#hugo-frontmatter) for details.
+- All changes to existing attributes, metrics, etc. MUST be allowed as
+  per our [stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/versioning-and-stability.md#semantic-conventions-stability) and
+  defined in a schema file.  As part of any contribution, you should
+  include attribute changes defined in the `schema-next.yaml` file.
+  For details, please read [the schema specification](https://opentelemetry.io/docs/specs/otel/schemas/).
+- After creating a pull request, please update the [CHANGELOG](CHANGELOG.md) file with
+  a description of your changes.
+  
+Please make sure all Pull Requests are compliant with these rules!
+
+### Hugo frontmatter
+
+At the top of all Markdown files under the `docs/` directory, you will see
+headers like the following:
+
+```
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: HTTP
+path_base_for_github_subdir:
+  from: content/en/docs/specs/semconv/http/_index.md
+  to: http/README.md
+--->
+```
+
+When creating new pages, you should provide the `linkTitle` attribute. This is used
+to generate the navigation bar on the website, and will be listed relative to the
+"parent" document.
+
+## Automation
+
+Semantic Conventions provides a set of automated tools for general development.
 
 ### Consistency Checks