# Contributing

Welcome to OpenTelemetry semantic conventions repository!

Before you start - see OpenTelemetry general
[contributing](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md)
requirements and recommendations.

## Sign the CLA

Before you can contribute, you will need to sign the [Contributor License
Agreement](https://identity.linuxfoundation.org/projects/cncf).

## TODO

We need to flesh out the rest of the contributing document for specifics on
semantic conventions.

### Consistency Checks

The Specification has a number of tools it uses to check things like style,
spelling and link validity. Before using the tools:

- Install the latest LTS release of **[Node](https://nodejs.org/)**.
For example, using **[nvm][]** under Linux run:

  ```bash
  nvm install --lts
  ```

- Install tooling packages:

  ```bash
  npm install
  ```

You can perform all checks locally using this command:

```bash
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.

See:

- [MarkdownStyle](#markdown-style)
- [Misspell Check](#misspell-check)
- Markdown link checking (docs TODO)

### YAML to Markdown

Semantic conventions are declared in YAML files and markdown tables are
generated from these files. Read about semantic convention updates [here](./semantic_conventions/README.md).

### Autoformatting

Semantic conventions have some autogenerated components and additionally can do
automatic style/spell correction. You can run all of this via:

```bash
make fix
```

You can also run these fixes individually.

See:

- [Misspell Correction](#misspell-check)
- Table Generation (docs TODO)

### Markdown style

Markdown files should be properly formatted before a pull request is sent out.
In this repository we follow the
[markdownlint rules](https://github.com/DavidAnson/markdownlint#rules--aliases)
with some customizations. See [markdownlint](.markdownlint.yaml) or
[settings](.vscode/settings.json) for details.

We highly encourage to use line breaks in markdown files at `80` characters
wide. There are tools that can do it for you effectively. Please submit proposal
to include your editor settings required to enable this behavior so the out of
the box settings for this repository will be consistent.

To check for style violations, run:

```bash
make markdownlint
```

To fix style violations, follow the
[instruction](https://github.com/DavidAnson/markdownlint#optionsresultversion)
with the Node version of markdownlint. If you are using Visual Studio Code,
you can also use the `fixAll` command of the
[vscode markdownlint extension](https://github.com/DavidAnson/vscode-markdownlint).

### Misspell check

In addition, please make sure to clean up typos before you submit the change.

To check for typos, run the following command:

```bash
make misspell
```

> **NOTE**: The `misspell` make target will also fetch and build the tool if
> necessary. You'll need [Go](https://go.dev) to build the spellchecker.

To quickly fix typos, use

```bash
make misspell-correction
```

## Updating the referenced specification version

1. Open the `./internal/tools/update_specification_version.sh` script.
2. Modify the `PREVIOUS_SPECIFICATION_VERSION` to be the same value as `LATEST_SPECIFICATION_VERSION`
3. Modify `LATEST_SPECIFICATION_VERSION` to the latest specification tag, e.g. `1.21`
4. Run the script from the root directory, e.g. `semantic-conventions$ ./internal/tools/update_specification_version.sh`.
5. Add all modified files to the change submit and submit a PR.