[editorial] A few random doc fixes (#1704)

Co-authored-by: Trask Stalnaker <[email protected]>
Co-authored-by: Joao Grassi <[email protected]>

Author: 3 people

CONTRIBUTING.md

@@ -20,8 +20,9 @@ requirements and recommendations.
     - [Schema files](#schema-files)
   - [2. Update the markdown files](#2-update-the-markdown-files)
     - [Hugo frontmatter](#hugo-frontmatter)
-  - [3. Verify the changes before committing](#3-verify-the-changes-before-committing)
-  - [4. Changelog](#4-changelog)
+  - [3. Check new convention](#3-check-new-convention)
+  - [4. Verify the changes before committing](#4-verify-the-changes-before-committing)
+  - [5. Changelog](#5-changelog)
     - [When to add a Changelog Entry](#when-to-add-a-changelog-entry)
       - [Examples](#examples)
     - [Adding a Changelog Entry](#adding-a-changelog-entry)
@@ -32,7 +33,6 @@ requirements and recommendations.
   - [Markdown style](#markdown-style)
   - [Misspell check](#misspell-check)
   - [Markdown link check](#markdown-link-check)
-  - [Version compatibility check](#version-compatibility-check)
 - [Updating the referenced specification version](#updating-the-referenced-specification-version)
 - [Making a Release](#making-a-release)
 - [Merging existing ECS conventions](#merging-existing-ecs-conventions)
@@ -126,6 +126,8 @@ The YAML (model definition) and Markdown (documentation) files are organized in
 │   │   ├── ....md
 ├── model
 │   ├── {root-namespace}
+│   │   ├── deprecated
+│   │   |   ├── registry-deprecated.yaml
 │   │   ├── events.yaml
 │   │   ├── metrics.yaml
 │   │   ├── registry.yaml
@@ -146,6 +148,9 @@ HTTP spans are defined in `model/http/spans.yaml`.
 YAML definitions could be broken down into multiple files. For example, AWS spans
 are defined in `/model/aws/lambda-spans.yaml` and `/model/aws/sdk-spans.yaml` files.
 
+Deprecated conventions should be placed under `/model/{root-namespace}/deprecated`
+folder.
+
 #### Schema files
 
 When making changes to existing semantic conventions (attributes, metrics, etc)
@@ -157,6 +162,7 @@ For details, please read
 You can also take examples from past changes inside the `schemas` folder.
 
 > [!WARNING]
+>
 > DO NOT add your changes to files inside the `schemas` folder. Always add your
 > changes to the `schema-next.yaml` file.
 
@@ -187,7 +193,21 @@ When creating new markdown files, 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.
 
-### 3. Verify the changes before committing
+### 3. Check new convention
+
+Semantic conventions are validated for name formatting and backward compatibility with last released versions.
+Here's [the full list of compatibility checks](./policies/compatibility.rego).
+
+Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead.
+It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes.
+
+You can run backward compatibility check (along with other policies) in all yaml files with the following command:
+
+```bash
+make check-policies
+```
+
+### 4. Verify the changes before committing
 
 Before sending a PR with your changes, make sure to run the automated checks:
 
@@ -198,7 +218,7 @@ make check
 Alternatively, you can run each check individually.
 Refer to the [Automation](#automation) section for more details.
 
-### 4. Changelog
+### 5. Changelog
 
 #### When to add a Changelog Entry
 
@@ -361,18 +381,6 @@ To check the validity of links in all markdown files, run the following command:
 make markdown-link-check
 ```
 
-### Version compatibility check
-
-Semantic conventions are validated for backward compatibility with last released versions. Here's [the full list of compatibility checks](./policies/compatibility.rego).
-Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead.
-It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes.
-
-You can run backward compatibility check (along with other policies) in all yaml files with the following command:
-
-```bash
-make check-policies
-```
-
 ## Updating the referenced specification version
 
 1. Open the `./internal/tools/update_specification_version.sh` script.

Makefile

@@ -183,7 +183,7 @@ fix-format:
 # Run all checks in order of speed / likely failure.
 # As a last thing, run attribute registry generation and git-diff for differences.
 .PHONY: check
-check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check check-policies attribute-registry-generation
+check: misspell markdownlint check-format markdown-toc markdown-link-check check-policies attribute-registry-generation
 	git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1)
 	@echo "All checks complete"
 

docs/attributes-registry/README.md

@@ -16,15 +16,16 @@ The attributes registry is the place where attributes are defined. An attribute
 - a `brief` description of the attribute and optionally a longer `note`
 - example values
 
-Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context.
+Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id`, `type` and `stability` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context.
 
 A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions.
 
 If applicable, application developers are encouraged to use existing attributes from this registry. See also [these recommendations][developers recommendations] regarding attribute selection and attribute naming for custom use cases.
 
 All registered attributes are listed by namespace in this registry.
 
-> **Warning**
+> [!WARNING]
+>
 > The following registry overview is a work in progress.
 >
 > Further attribute namespaces are currently being migrated and will appear in this registry soon.
@@ -45,12 +46,12 @@ Currently, the following namespaces exist:
 - [Code](code.md)
 - [Container](container.md)
 - [CPU](cpu.md)
-- [Db](db.md)
+- [DB](db.md)
 - [Deployment](deployment.md)
 - [Destination](destination.md)
 - [Device](device.md)
 - [Disk](disk.md)
-- [Dns](dns.md)
+- [DNS](dns.md)
 - [Dotnet](dotnet.md)
 - [Enduser](enduser.md)
 - [Error](error.md)

docs/attributes-registry/db.md

@@ -4,7 +4,7 @@
 <!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
 
-# Db
+# DB
 
 - [General Database Attributes](#general-database-attributes)
 - [Cassandra Attributes](#cassandra-attributes)

docs/attributes-registry/dns.md

@@ -4,7 +4,7 @@
 <!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
 
-# Dns
+# DNS
 
 ## DNS Attributes
 

docs/gen-ai/gen-ai-events.md

@@ -25,13 +25,8 @@ linkTitle: Generative AI events
 
 GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md#emit-an-event).
 
-<<<<<<< HEAD
-> [!NOTE]
-> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#events) to see the implementation status in corresponding language.
-=======
 > Note:
 > Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language.
->>>>>>> 75746bc9 (reword)
 
 Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data.
 This is for three primary reasons:

docs/general/group-stability.md renamed to docs/general/semantic-convention-groups.md

@@ -4,8 +4,10 @@ The YAML descriptions of semantic convention contained in this directory are int
 be used by the various OpenTelemetry language implementations to aid in automatic
 generation of semantics-related code.
 
-⚠ If you want to read the semantic conventions and not edit them, please see
-the generated markdown output in the [docs](../docs/README.md) folder.
+> [!NOTE]
+>
+> If you want to read the semantic conventions and not edit them, please see
+> the generated markdown output in the [docs](../docs/README.md) folder.
 
 ## Writing semantic conventions
 
@@ -21,18 +23,36 @@ A schema file for VS code is configured in the `/.vscode/settings.json` of this
 repository, enabling auto-completion and additional checks. Refer to
 [the generator README](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md) for what extension you need.
 
+When defining semantic conventions, follow [contributing guide](/CONTRIBUTING.md#1-modify-the-yaml-model):
+
+- If new attributes are necessary, define them in the [attribute registry](/docs/attributes-registry/README.md).
+  Attributes can only be defined inside groups with `attribute_group` type and with `id` starting with `registry.` prefix.
+- Define new spans, metrics, events, resources, and other conventions using appropriate group type. See
+  [semantic convention groups](/docs/general/semantic-convention-groups.md) for more details.
+
 ## Generating markdown
 
-These YAML files are used by the make target `table-generation` to generate consistently
+These YAML files are used by the make targets `attribute-registry-generation` and `table-generation` to generate consistently
 formatted Markdown tables for all semantic conventions in the specification. Run it from the root of this repository using the command
 
 ```
-make table-generation
+make attribute-registry-generation table-generation
 ```
 
 For more information, see the [Weaver](https://github.com/open-telemetry/weaver)
 as our code generations tool.
 
+## Validating semantic conventions
+
+Semantic conventions YAML files are validated by the `check-policies` make target for backward compatibility,
+name formatting, and other policies.
+
+You can run it with the following command:
+
+```
+make check-policies
+```
+
 See also:
 
 * [Markdown Templates](../templates/registry/markdown)

model/README.md

@@ -17,15 +17,16 @@ The attributes registry is the place where attributes are defined. An attribute
 - a `brief` description of the attribute and optionally a longer `note`
 - example values
 
-Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context.
+Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id`, `type` and `stability` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context.
 
 A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions.
 
 If applicable, application developers are encouraged to use existing attributes from this registry. See also [these recommendations][developers recommendations] regarding attribute selection and attribute naming for custom use cases.
 
 All registered attributes are listed by namespace in this registry.
 
-> **Warning**
+> [!WARNING]
+>
 > The following registry overview is a work in progress.
 >
 > Further attribute namespaces are currently being migrated and will appear in this registry soon.

templates/registry/markdown/readme.md.j2

@@ -14,6 +14,8 @@ acronyms:
   - CLR
   - CPU
   - CSI
+  - DB
+  - DNS
   - DynamoDB
   - ECS
   - EKS