Skip to content

Latest commit

 

History

History
124 lines (84 loc) · 3.56 KB

CONTRIBUTING.md

File metadata and controls

124 lines (84 loc) · 3.56 KB
Raw

Contributing

Welcome to OpenTelemetry semantic conventions repository!

Before you start - see OpenTelemetry general contributing requirements and recommendations.

Sign the CLA

Before you can contribute, you will need to sign the Contributor License Agreement.

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. For example, using [nvm][] under Linux run:

    nvm install --lts

  • Install tooling packages:

    npm install

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.

See:

YAML to Markdown

Semantic conventions are declared in YAML files and markdown tables are generated from these files. Read about semantic convention updates here.

Autoformatting

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

make fix

You can also run these fixes individually.

See:

Markdown style

Markdown files should be properly formatted before a pull request is sent out. In this repository we follow the markdownlint rules with some customizations. See markdownlint or settings 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:

make markdownlint

To fix style violations, follow the instruction 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.

Misspell check

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

To check for typos, run the following command:

make misspell

NOTE: The misspell make target will also fetch and build the tool if necessary. You'll need Go to build the spellchecker.

To quickly fix typos, use

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.