diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0bfa90bc98..17a158ea99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,38 @@ Before you start - see OpenTelemetry general [contributing](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md) requirements and recommendations. +
+Table of Contents + + + +- [Sign the CLA](#sign-the-cla) +- [How to Contribute](#how-to-contribute) + * [Prerequisites](#prerequisites) + * [1. Modify the YAML model](#1-modify-the-yaml-model) + + [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) + + [When to add a Changelog Entry](#when-to-add-a-changelog-entry) + - [Examples](#examples) + + [Adding a Changelog Entry](#adding-a-changelog-entry) + * [4. Getting your PR merged](#4-getting-your-pr-merged) +- [Automation](#automation) + * [Consistency Checks](#consistency-checks) + * [Auto formatting](#auto-formatting) + * [Markdown style](#markdown-style) + * [Misspell check](#misspell-check) + * [Markdown link check](#markdown-link-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) + + + +
+ ## Sign the CLA Before you can contribute, you will need to sign the [Contributor License @@ -18,31 +50,70 @@ 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 ` ``` -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. +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. -## Automation +### 3. Verify the changes before committing -Semantic Conventions provides a set of automated tools for general development. +Before sending a PR with your changes, make sure to run the automated checks: -### Consistency Checks +```bash +make check +``` -The Specification has a number of tools it uses to check things like style, -spelling and link validity. Before using the tools: +Alternatively, you can run each check individually. +Refer to the [Automation](#automation) section for more details. -- Install the latest LTS release of **[Node](https://nodejs.org/)**. - For example, using **[nvm][]** under Linux run: +### 4. Changelog - ```bash - nvm install --lts - ``` +#### When to add a Changelog Entry -- Install tooling packages: +Pull requests that contain user-facing changes will require a changelog entry. +Keep in mind the following types of users (not limited to): - ```bash - npm install - ``` +1. Those who are consuming the conventions (e.g. in alerts, dashboards, queries) +2. Those who are using the conventions in instrumentations (e.g., library authors) +3. Those who are using the conventions to derive heuristics, predictions and automatic analyses (e.g. observability products/back-ends) + +If a changelog entry is not required (e.g. editorial or trivial changes), +a maintainer or approver will add the `Skip Changelog` label to the pull request. + +##### Examples + +Changelog entry required: + +- Any modification to existing conventions with change in functionality/behavior +- New semantic conventions +- Changes on definitions, normative language (in `/docs`) + +Judgement call: + +No changelog entry: + +- Typical documentation/editorial updates (e.g. grammar fixes, restructuring) +- Changes in internal tooling (e.g. make file, GH actions, etc) +- Refactorings with no meaningful change in functionality +- Chores, such as enabling linters, or minor changes to the CI process + +#### Adding a Changelog Entry + +The [CHANGELOG.md](./CHANGELOG.md) files in this repo is autogenerated +from `.yaml` files in the `./.chloggen` directory. + +Your pull-request should add a new `.yaml` file to this directory. +The name of your file must be unique since the last release. + +During the release process, all `./chloggen/*.yaml` files are transcribed into +`CHANGELOG.md` and then deleted. + +1. Create an entry file using `make chlog-new`. This generates a file based + on your current branch (e.g. `./.chloggen/my-branch.yaml`) +2. Fill in all fields in the new file +3. Run `make chlog-validate` to ensure the new file is valid +4. Commit and push the file + +Alternately, copy `./.chloggen/TEMPLATE.yaml`, or just create your file from scratch. + +### 4. Getting your PR merged + +A PR (pull request) is considered to be **ready to merge** when: + +- It has received at least two approvals from the [code + owners](./.github/CODEOWNERS) (if approvals are from only one company, they + won't count) +- There is no `request changes` from the [code owners](./.github/CODEOWNERS) +- There is no open discussions +- It has been at least two working days since the last modification (except for + the trivial updates, such like typo, cosmetic, rebase, etc.). This gives + people reasonable time to review +- Trivial changes (typos, cosmetic changes, CI improvements, etc.) don't have to + wait for two days + +Any [maintainer](./README.md#contributing) can merge the PR once it is **ready +to merge**. + +## Automation + +Semantic Conventions provides a set of automated tools for general development. + +### Consistency Checks + +The Specification has a number of tools it uses to check things like style, +spelling and link validity. You can perform all checks locally using this command: @@ -83,23 +220,18 @@ You can perform all checks locally using this command: make check ``` -Note: This can take a long time as it checks all links. You should use this -prior to submitting a PR to ensure validity. However, you can run individual -checks directly. +> Note: `make check` can take a long time as it checks all links. +> You should use this prior to submitting a PR to ensure validity. +> However, you can run individual checks directly. -See: +For more information on each check, see: -- [MarkdownStyle](#markdown-style) -- [Misspell Check](#misspell-check) -- Markdown link checking (docs TODO) +- [Markdown style](#markdown-style) +- [Misspell check](#misspell-check) +- [Markdown link check](#markdown-link-check) - Prettier formatting -### YAML to Markdown - -Semantic conventions are declared in YAML files and markdown tables are -generated from these files. Read about semantic convention updates [here](./model/README.md). - -### Autoformatting +### Auto formatting Semantic conventions have some autogenerated components and additionally can do automatic style/spell correction. You can run all of this via: @@ -113,7 +245,7 @@ You can also run these fixes individually. See: - [Misspell Correction](#misspell-check) -- Table Generation (docs TODO) +- [Update the markdown files](#2-update-the-markdown-files) ### Markdown style @@ -159,22 +291,13 @@ To quickly fix typos, use make misspell-correction ``` -### How to get your PR merged +### Markdown link check -A PR (pull request) is considered to be **ready to merge** when: +To check the validity of links in all markdown files, run the following command: -- It has received at least two approvals from the [code - owners](./.github/CODEOWNERS) (if approvals are from only one company, they - won't count). -- There is no `request changes` from the [code owners](./.github/CODEOWNERS). -- It has been at least two working days since the last modification (except for - the trivial updates, such like typo, cosmetic, rebase, etc.). This gives - people reasonable time to review. -- Trivial changes (typos, cosmetic changes, CI improvements, etc.) don't have to - wait for two days. - -Any [maintainer](./README.md#contributing) can merge the PR once it is **ready -to merge**. +```bash +make markdown-link-check +``` ## Updating the referenced specification version