Skip to main content
We welcome contributions to the Halo measurement system! This guide explains the process for submitting patches and contributions to the project.

​
Before You Begin

Read the Docs

Familiarize yourself with the Development Standards and Code Style guidelines.

Set Up Your Environment

Follow the Building and IntelliJ Setup guides to configure your development environment.

​
Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA).
You (or your employer) retain the copyright to your contribution. The CLA simply gives the project permission to use and redistribute your contributions as part of the project.

​
Signing the CLA

1

Check if you've signed

If you’ve already submitted a CLA for any project in the World Federation of Advertisers organization, you likely don’t need to do it again.
2

Submit the CLA

When you submit your first pull request, you’ll be prompted to sign the CLA if you haven’t already.
3

Wait for verification

The CLA bot will verify your signature before your PR can be merged.

​
Contribution Workflow

​
1. Find or Create an Issue

1

Search existing issues

Check if there’s already an issue for the work you want to do in the GitHub Issues.
2

Create a new issue

If no relevant issue exists:
  • Use the appropriate issue template (Bug, Feature Request, etc.)
  • Write a clear, self-contained title
  • Provide detailed description and context
  • Add appropriate labels and type
3

Discuss before major changes

For significant changes, discuss your approach in the issue before starting work.
Every PR should be associated with at least one GitHub issue. This helps track the context and reasoning behind changes.

​
2. Create a Branch

# Update your main branch
git checkout main
git pull origin main

# Create a feature branch
git checkout -b feature/your-feature-name

​
3. Make Your Changes

1

Write code

Implement your changes following the Development Standards.
2

Add tests

  • Write unit tests for new functionality
  • Ensure existing tests still pass
  • See Testing Guide for details
3

Update documentation

Update relevant documentation for your changes, including:
  • Code comments
  • README files
  • API documentation

​
4. Format and Lint

Before committing, ensure your code is properly formatted: 
# Format Kotlin files
ktfmt --google-style src/main/kotlin/**/*.kt
ktfmt --google-style src/test/kotlin/**/*.kt

​
5. Run Tests

Verify all tests pass: 
# Run all tests
bazel test //src/test/...

# Or use containerized build
tools/bazel-container test //src/test/...

​
6. Commit Your Changes

Follow the Conventional Commits specification: 
git add .
git commit -m "feat(component): Add new feature

Detailed description of the change and why it was made.

Issue: world-federation-of-advertisers/cross-media-measurement#123"
See Commit Message Format for detailed guidelines.

​
7. Push and Create Pull Request

# Push your branch
git push origin feature/your-feature-name
Then:
1

Open PR on GitHub

Navigate to the repository and click “New Pull Request”
2

Fill out PR template

  • Write a clear title following commit message format
  • Provide detailed description
  • Reference related issues using Issue: org/repo#number
  • List breaking changes if any
3

Review your own PR first

Before adding reviewers:
  • Check for typos
  • Verify tests pass
  • Ensure documentation is complete
  • Look for DO_NOT_SUBMIT markers

​
Code Review Process

All submissions require review through Reviewable.io.
1

Wait for automated checks

CI/CD pipelines will automatically:
  • Run tests
  • Check formatting
  • Verify build succeeds
  • Check for DO_NOT_SUBMIT markers
2

Address review comments

  • Respond to feedback in Reviewable
  • Make requested changes
  • Push updates to your branch
  • Mark comments as “Satisfied” when addressed
3

Get approval

Once all blocking comments are resolved, the reviewer will approve.
4

Merge

After approval and passing checks:
  • A maintainer will merge your PR through GitHub UI
  • Ensure commit message is properly formatted (remove GitHub’s line wrapping)
Remove any line wrapping that GitHub introduces into the PR title and final commit message to ensure parseability.

​
Contribution Guidelines

​
Do’s

Write Tests

All new code should include comprehensive unit tests

Follow Style Guides

Use automated formatters and follow language-specific guidelines

Document Changes

Update docs, add comments, explain complex logic

Keep PRs Focused

One logical change per PR makes review easier

​
Don’ts

Don't Mix Concerns

Avoid combining refactoring with feature changes

Don't Skip Tests

Never submit code without running the test suite

Don't Add Secrets

Never commit credentials, API keys, or sensitive data

Don't Break Builds

Ensure your changes don’t introduce build failures

​
Types of Contributions

​
Bug Fixes

  1. Create or find a bug issue
  2. Write a failing test that reproduces the bug
  3. Fix the bug
  4. Verify the test now passes
  5. Submit PR with fix: commit type

​
New Features

  1. Discuss the feature in an issue first
  2. Design the API/interface
  3. Implement with comprehensive tests
  4. Update documentation
  5. Submit PR with feat: commit type

​
Documentation

  1. Identify gaps or errors in documentation
  2. Make improvements
  3. Submit PR with docs: commit type

​
Performance Improvements

  1. Create an issue with benchmarks showing the problem
  2. Implement optimization
  3. Provide before/after benchmarks
  4. Submit PR with perf: commit type

​
Getting Help

GitHub Issues

Ask questions or report problems in GitHub Issues

Discussions

Start a discussion for broader topics or questions

​
Recognition

Contributors are recognized through:
  • GitHub commit history
  • Release notes for significant contributions
  • Public acknowledgment in project communications
By contributing, you agree that your contributions will be licensed under the same license as the project (Apache 2.0).

​
Next Steps

Dev Standards

Review commit and code review standards

Building

Learn about the build system

Testing

Understand testing requirements

​
Thank You!

Thank you for contributing to the Halo Cross-Media Measurement System! Your contributions help advance privacy-preserving measurement for the advertising industry.

Build docs developers (and LLMs) love

Get started for freeTalk to us