Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
337 lines (248 loc) · 13.2 KB

CONTRIBUTING.md

File metadata and controls

337 lines (248 loc) · 13.2 KB

Contributing to opentelemetry-go-compile-instrumentation

The go compile instrumentation SIG meets regularly. See the OpenTelemetry community repo for information on this and other SIGs.

See the public meeting notes for a summary description of past meetings. You can also get in touch on slack channel #otel-go-compt-instr-sig

Development

Prerequisites

This project uses several tools for development. Most tools will be automatically installed when you first run the corresponding make target. However, you need to have:

  • Go 1.21 or later
  • Git
  • Make (usually pre-installed on macOS and Linux)

Getting Started

  1. Clone the repository:

    git clone https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation
cd opentelemetry-go-compile-instrumentation

  2. Build the project:

    make build

  3. Run tests:

    make test

Available Make Targets

Run make help to see all available targets:

make help

Build Targets

  • make build - Build the instrumentation tool (includes packaging)
  • make install - Install the otel binary to $GOPATH/bin
  • make package - Package the instrumentation code into a binary archive
  • make build-demo-grpc - Build gRPC demo server and client

Code Quality

  • make format - Format all code (Go + YAML + License Headers)
    • make format/go - Format Go code only using golangci-lint
    • make format/yaml - Format YAML files only using yamlfmt
    • make format/license - Apply license headers to Go files
  • make lint - Run all linters (Go, YAML, GitHub Actions, Makefile)
    • make lint/go - Run golangci-lint on Go code
    • make lint/yaml - Lint YAML formatting
    • make lint/action - Lint GitHub Actions workflows
    • make lint/makefile - Lint Makefile
    • make lint/license - Check license headers (has dedicated CI workflow)

License Headers

All Go files must include the proper license header. The license header configuration is defined in license.yml which handles exclusions for vendor directories, temporary files, and generated code.

To check and fix license headers:

  • Check license headers: make lint/license
  • Apply license headers: make format/license

The license header checker has a dedicated CI workflow (check-license-headers.yaml) that runs automatically on pull requests and pushes when Go files or the license configuration change.

Testing

  • make test - Run all tests (unit + integration)
  • make test-unit - Run unit tests only with formatted output
  • make test-integration - Run integration tests only with formatted output

Test results are saved to gotest-unit.log and gotest-integration.log for review.

Documentation

  • make docs - Update embedded documentation in markdown files

Semantic Conventions

  • make weaver-install - Install OTel Weaver if not present
  • make lint/semantic-conventions - Validate semantic convention registry
  • make registry-diff - Generate diff between two versions of semantic convention registry
  • make semantic-conventions/resolve - Resolve semantic convention registry schema

For detailed information on managing semantic conventions, see docs/semantic-conventions.md.

GitHub Actions Security

  • make ratchet/pin - Pin GitHub Actions to specific commit SHAs for security
  • make ratchet/update - Update pinned GitHub Actions to latest versions
  • make ratchet/check - Verify all GitHub Actions are properly pinned

Cleanup

  • make clean - Remove all build artifacts and temporary files

Development Workflow

A typical development workflow looks like:

  1. Make your changes
  2. Format your code: make format
  3. Run linters: make lint
  4. Run tests: make test
  5. Commit your changes

For a complete check before submitting a PR, run:

make all

This will run: build, format, lint, and test in sequence.

Tools

The following development tools are used and will be automatically installed on first use:

Pull Requests

Conventional Commits

Pull requests made to this repository are expected to use the Conventional Commits specification. Specifically, pull request titles are required to follow the specification's title format:

<type>(<scope>)!: <description>
╰─┬──╯╰───┬───╯│  ╰─────┬─────╯
  │       │    │        ╰─ Short description of the change (see below)
  │       │    ╰─ If, and only if the PR contains breaking changes
  │       ╰─ Optional: change scope (e.g, 'cmd/gotel', `pkg/weaver`, ...)
  ╰─ Required: commit type (see below for accepted values)

This repository requires using one of the following commit types:

  • chore for routine repository maintenance that has no impact on the user interfaces (CI/CD operations, linter configuration, etc...)
  • doc or docs for documentation changes
  • feat for introduction of new features
  • fix for bug fixes
  • release when cutting a new release
  • refactor for code changes that do not add new features or fix bugs

Please try to keep the commit title concise, yet specific: they are used to derive the release notes for this repository. A good litmus test for whether a pull request title is suitable or not is to determine whether a user would be able to determine whether this change affects them or not by just looking at the title.

Here are some examples for the various supported commit types:

  • chore:
    • ℹ️ What's changing in this PR? This should provide enough information from a maintainer to make sense of what's going on.
    • ✅ chore(ci): add OSSF Scorecard automation
    • ❌ chore: new CI step
  • doc, docs:
    • ℹ️ What documentation has change? A user might decide whether they go read it or not based on this.
    • ✅ docs: explain proper use of the -log-level flag
    • ❌ docs: improve documentation
  • feat:
    • ℹ️ What feature is being introduced specifically? A user might decide if this is useful to them or not based on this.
    • ✅ feat(cmd/gotel): -log-level flag to configure log verbosity
    • ❌ feat: logging
  • fix:
    • ℹ️ What bug is being fixed? Refer to the symptoms of the fixed issue, not to the solution. A user might decide whether their problem is solved by a release or not based on this.
    • ✅ fix: SEGFAULT on when cross-compiling on linux/arm64 platforms
    • ❌ fix: check pointer for nil before dereferencing it
  • release:
    • ℹ️ What version is this commit preparing for?
    • ✅ release: v1.2.3
    • ❌ release: new release
  • refactor:
    • ℹ️ What code is being refactored?
    • ✅ refactor: remove unused code
    • ❌ refactor: improve code readability

How to Send Pull Requests

Everyone is welcome to contribute code to opentelemetry-go-compile-instrumentation via GitHub pull requests (PRs).

To create a new PR, fork the project in GitHub and clone the upstream repo:

git clone https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation

This would put the project in the opentelemetry-go-compile-instrumentation directory in current working directory.

Enter the newly created directory and add your fork as a new remote:

git remote add <YOUR_FORK> git@github.com:<YOUR_GITHUB_USERNAME>/opentelemetry-go-compile-instrumentation

Check out a new branch, make modifications, run linters and tests, update CHANGELOG.md, and push the branch to your fork:

git checkout -b <YOUR_BRANCH_NAME>
# edit files
# update changelog
git add -p
git commit
git push <YOUR_FORK> <YOUR_BRANCH_NAME>

Open a pull request against the main opentelemetry-go-compile-instrumentation repo. Be sure to add the pull request ID to the entry you added to CHANGELOG.md.

Avoid rebasing and force-pushing to your branch to facilitate reviewing the pull request. Rewriting Git history makes it difficult to keep track of iterations during code review. All pull requests are squashed to a single commit upon merge to main.

How to Receive Comments

  • If the PR is not ready for review, please put [WIP] in the title, tag it as work-in-progress, or mark it as draft.
  • Make sure CLA is signed and CI is clear.

How to Get PRs Merged

A PR is considered ready to merge when:

  • It has received two qualified approvals1.

    This is not enforced through automation, but needs to be validated by the maintainer merging.

    • The qualified approvals need to be from [Approver]s/[Maintainer]s affiliated with different companies. Two qualified approvals from [Approver]s or [Maintainer]s affiliated with the same company counts as a single qualified approval.
    • PRs introducing changes that have already been discussed and consensus reached only need one qualified approval. The discussion and resolution needs to be linked to the PR.
    • Trivial changes2 only need one qualified approval.

  • All feedback has been addressed.

    • All PR comments and suggestions are resolved.
    • All GitHub Pull Request reviews with a status of "Request changes" have been addressed. Another review by the objecting reviewer with a different status can be submitted to clear the original review, or the review can be dismissed by a [Maintainer] when the issues from the original review have been addressed.
    • Any comments or reviews that cannot be resolved between the PR author and reviewers can be submitted to the community [Approver]s and [Maintainer]s during the weekly SIG meeting. If consensus is reached among the [Approver]s and [Maintainer]s during the SIG meeting the objections to the PR may be dismissed or resolved or the PR closed by a [Maintainer].
    • Any substantive changes to the PR require existing Approval reviews be cleared unless the approver explicitly states that their approval persists across changes. This includes changes resulting from other feedback. [Approver]s and [Maintainer]s can help in clearing reviews and they should be consulted if there are any questions.

  • The PR branch is up to date with the base branch it is merging into.

    • To ensure this does not block the PR, it should be configured to allow maintainers to update it.

  • It has been open for review for at least one working day. This gives people reasonable time to review.

    • Trivial changes2 do not have to wait for one day and may be merged with a single [Maintainer]'s approval.

  • All required GitHub workflows have succeeded.

  • Urgent fix can take exception as long as it has been actively communicated among [Maintainer]s.

Any [Maintainer] can merge the PR once the above criteria have been met.

Approvers and Maintainers

Maintainers

For more information about the maintainer role, see the community repository.

Approvers

For more information about the approver role, see the community repository.

Emeritus maintainers

For more information about the emeritus role, see the community repository.

Footnotes

  1. A qualified approval is a GitHub Pull Request review with "Approve" status from an OpenTelemetry Go Compile Instrumentation [Approver] or [Maintainer]. ↩

  2. Trivial changes include: typo corrections, cosmetic non-substantive changes, documentation corrections or updates, dependency updates, etc. ↩ ↩2