Skip to content

Latest commit

 

History

History
203 lines (148 loc) · 7.09 KB

CONTRIBUTING.md

File metadata and controls

203 lines (148 loc) · 7.09 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.

How to Contribute

When contributing to semantic conventions, it's important to understand a few 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.
  • All changes to existing attributes, metrics, etc. MUST be allowed as per our stability guarantees and defined in a schema file. As part of any contribution, you should include attribute changes defined in the schema-next.yaml file. For details, please read the schema specification.
  • Links to the specification repository MUST point to a tag and not to the main branch. The tag version MUST match with the one defined in README.
  • After creating a pull request, please update the CHANGELOG file with a description of your changes.

Please make sure all Pull Requests are compliant with these rules!

Hugo frontmatter

At the top of all Markdown files under the docs/ directory, you will see headers like the following:

<!--- Hugo front matter used to generate the website version of this page:
linkTitle: HTTP
path_base_for_github_subdir:
  from: content/en/docs/specs/semconv/http/_index.md
  to: http/README.md
--->

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.

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

How to get 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 (if approvals are from only one company, they won't count).
  • There is no request changes from the code owners.
  • 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 can merge the PR once it is ready to merge.

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.

Making a Release

  • Ensure the referenced specification version is up to date. Use tooling to update the spec if needed.
  • Create a staging branch for the release.
    • Update schema-next.yaml file and move to schemas/{version}
      • Ensure the next version is appropriately configured as the {version}.
      • Copy schema-next.yaml to schemas/{version}.
      • Add next as a version in schema-next.yaml version.
    • Update CHANGELOG.md for the latest version.
      • Add ## v{version} ({date}) under ## Unreleased
    • Send staging tag as PR for review.
  • Create a tag v{version} on the merged PR and push remote.