125 lines
3.6 KiB
Markdown
125 lines
3.6 KiB
Markdown
# 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.
|