Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (128 loc) · 6.71 KB

CONTRIBUTING.md

File metadata and controls

178 lines (128 loc) · 6.71 KB
Raw

Contributing

Welcome to OpenTelemetry specifications 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.

Proposing a Change

Trivial Changes

Examples: fixing a typo, rewording a sentence for clarity, correcting a broken link.

Clarifications, wording, spelling/grammar, and formatting fixes can be made directly via pull request with no associated issue.

Smaller Changes

Examples: defining a new term, adding a new optional parameter to an existing API, stabilizing an existing feature, tightening a SHOULD to a MUST.

Create an issue describing the proposed change and wait for acceptance before opening a PR. If the issue is not accepted, the PR will be rejected. See issue-management.md for the full issue lifecycle, triage labels, and role definitions.

A Draft PR may be opened alongside the issue to illustrate the idea before it is accepted.

The PR description must include links to prototypes:

  • For new features at Development maturity level, a prototype is required. It should be a working demonstration in a spec-bound implementation with that SIG's maintainers' support (e.g. an unmerged PR with stated intent to merge if the spec PR is merged).
  • Before a feature can be stabilized, prototypes in multiple languages are required. The number is at the discretion of the spec maintainers, though three is typical.

If the change adds or modifies SDK component configuration, the PR must link to a corresponding proposed change to the declarative configuration schema. These PRs should be approved and merged together.

Significant Changes

Examples: new metric types (e.g. exponential histograms), new signals (e.g. Events and Logs API), new cross-cutting systems (e.g. declarative configuration).

Significant changes should go through the OpenTelemetry Enhancement Proposal process. See the OTEP README for guidance on what changes require an OTEP.

Writing Specs

Specification is written in Markdown. Please make sure files render correctly on GitHub. We highly encourage line breaks at 80 characters wide — there are editor tools that can do this automatically. Please submit a proposal to include your editor settings so the out-of-the-box configuration for this repository stays consistent.

Clearly define requirements using the keywords defined in Notation Conventions and Compliance, while heeding the guidance in RFC 2119 about sparing use of imperatives:

Imperatives of the type defined in this memo must be used with care and sparingly. In particular, they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmissions). For example, they must not be used to try to impose a particular method on implementors where the method is not required for interoperability.

It is important to build a specification that is clear and useful, not one that is needlessly restrictive and complex.

Please see Specification Principles for more information.

Tooling

Install the latest LTS release of Node.js and run npm install before using any of the targets below. For example, using nvm under Linux:

nvm install --lts

Checks

Run all checks (spell, lint, style, links):

make check

Note

Link checking requires Docker and can take a long time. Run it before submitting a PR.

Run checks individually:

make language-analysis  # spell (cspell) and prose (textlint)
make markdownlint       # Markdown style
make markdown-link-check # link validity (requires Docker)

See markdownlint for the full rule set.

Autofixes

make fix          # fix textlint violations
make markdown-toc # regenerate tables of contents

To fix markdownlint violations, use the Visual Studio Code markdownlint extension fixAll command, or follow the markdownlint instructions.

Compliance Matrix

To update the compliance matrix, edit the language YAML file in spec-compliance-matrix/ (e.g. go.yaml, java.yaml) and regenerate:

make compliance-matrix

Compliance matrix updates do not require a CHANGELOG entry. Use a chore: prefix in the PR title (e.g., chore: Update .NET compliance matrix).

Pull Requests

A PR is ready to merge when:

  • It has received two or more approvals from code owners, with approvals from at least two companies.
  • There are no outstanding request changes from code owners.
  • It has been at least two working days since the last modification (not required for trivial changes such as typos, cosmetic fixes, or rebases).
  • For non-trivial changes, the Unreleased section of CHANGELOG.md has been updated under the appropriate subsection.

Any spec maintainer can merge a PR that is ready to merge. Maintainers may impose additional requirements at their discretion (e.g. more approvals, waiting for a release).

If a PR is stuck, the owner should:

  • Post a summary of open perspectives in the PR description.
  • Tag relevant subdomain experts (check the change history).
  • Raise it in the #otel-specification channel on CNCF Slack. If you are new to the CNCF Slack community, you can create an account.
  • Consider narrowing the scope or splitting the PR.

If still stuck after two weeks, bring it to the OpenTelemetry Specification SIG meeting.