Skip to main content
NativeLink welcomes contribution from everyone. This guide provides the essential information to help you get started with contributing to NativeLink.

​
Contribution Process

Contributions to NativeLink or its dependencies should be made in the form of GitHub pull requests. Each pull request will be reviewed by a core contributor (someone with permission to land patches) and either landed in the main tree or given feedback for changes that would be required. Should you wish to work on an issue, please claim it first by commenting on the GitHub issue that you want to work on it. This is to prevent duplicated efforts from contributors on the same issue.

​
Development Environment

NativeLink supports multiple development workflows:

Nix

Recommended development environment with reproducible builds

Bazel

Primary build system for production builds and testing

Cargo

Direct Rust development with Cargo toolchain

​
Before You Start

​
Git Setup

NativeLink has a specific contribution process to ensure consistent quality across all commits:
1

Configure SSH Keys

In your GitHub settings, set up distinct authentication and signing keys. See GitHub’s documentation:
2

Fork the Repository

Fork the TraceMachina/nativelink repository by clicking on the Fork button on GitHub.
3

Clone Your Fork

git clone [email protected]:yourusername/nativelink
cd nativelink
Don’t clone the upstream repository directly:
# ❌ Don't do this
git clone [email protected]:TraceMachina/nativelink
4

Add Upstream Remote

git remote add upstream [email protected]:TraceMachina/nativelink
Verify the setup:
git remote -v
# Should show:
# origin   [email protected]:yourusername/nativelink (fetch)
# origin   [email protected]:yourusername/nativelink (push)
# upstream [email protected]:TraceMachina/nativelink (fetch)
# upstream [email protected]:TraceMachina/nativelink (push)
5

Configure Commit Signing

Create a .gitconfig file in your home directory:
[user]
    name = Your Full Name
    email = [email protected]
    signingkey = ~/.ssh/your_private_signing_key

[gpg]
    format = ssh  # Or gpg if you use a GPG key

[commit]
    gpgsign = true

[tag]
    gpgsign = true

​
Development Workflows

​
Building from Source

Choose your preferred build method:
  • Nix - Recommended for reproducible builds and CI parity
  • Bazel - Primary build system with remote execution support
  • Cargo - Standard Rust development workflow
See Building from Source for detailed instructions.

​
Code Quality

NativeLink maintains high code quality standards:
  • Pre-commit Hooks: Run pre-commit run -a to check formatting and lints
  • Rust Formatting: Automatically enforced via rustfmt
  • Clippy Lints: Strict linting rules defined in Cargo.toml
  • Documentation Tests: Run bazel test doctests to verify code examples

​
Testing

Test your changes thoroughly: 
# Run unit tests with Bazel
bazel test //...

# Run specific test suite
bazel test :unit_tests

# Run with Cargo
cargo test --all

​
Creating Pull Requests

1

Update Your Fork

git switch main
git pull -r upstream main
git push
2

Create Feature Branch

git switch -c some-feature
3

Make Changes and Commit

Follow commit message guidelines:
  • Use imperative mood (“Add feature” not “Adds feature”)
  • Start with capital letter
  • No trailing period
  • Keep title under 50 characters
  • Add details in commit body (72 char line length)
# Good examples:
Add remote execution support for workers
Fix memory leak in cache store
Update documentation for configuration

# Bad examples:
Adds feature.  # Wrong mood, has period
add feature    # Not capitalized
4

Push and Create PR

git push --set-upstream origin some-feature
Go to Pull Requests and create your PR.
5

Review Process

Click the purple Reviewable button and add reviewers with +@reviewer.If you need to make changes:
# Make your changes
git commit --amend
git push -f

​
Common Tasks

​
Fixing Rust Formatting

bazel run --config=rustfmt @rules_rust//:rustfmt

​
Running Pre-commit Hooks

pre-commit run -a

​
Setting up rust-analyzer

Generate project configuration for your IDE: 
bazel run @rules_rust//tools/rust_analyzer:gen_rust_project

​
Generating Documentation

# All documentation (in Nix environment)
docs

# With Bazel
bazel build docs

# Single crate
bazel build nativelink-config:docs

# Run doc tests
bazel test doctests

​
Generating Code Coverage

nix build .#nativelinkCoverageForHost
# View results in ./result/index.html

​
Documentation Style

NativeLink follows the Microsoft Style Guide. Check documentation with Vale: 
vale somefile
Pre-commit hooks forbid errors but permit warnings and suggestions.

​
Code of Conduct

NativeLink’s Code of Conduct is available in the CODE_OF_CONDUCT file.

​
Next Steps

Build from Source

Learn how to build NativeLink locally

Development with Nix

Set up the recommended development environment

Development with Bazel

Use Bazel for building and testing

Development with Cargo

Work with standard Rust tooling

Build docs developers (and LLMs) love

Get started for freeTalk to us