Contributing - Internet Computer

Thank you for your interest in contributing to the Internet Computer Protocol! This guide covers the process for submitting contributions, understanding CI/CD workflows, and adhering to coding standards.

Before You Start

Important: Reach out to us first before contributing a feature or bug fix so we can discuss feasibility and implementation strategies.

You can engage with the community on the DFINITY Forum.

Contribution License Agreement

All contributors must agree to the terms outlined in:

If this is your first contribution to a DFINITY repository, you’ll be prompted to sign the CLA when you submit your pull request.

Getting Started

1. Fork the Repository

Fork

Fork the dfinity/ic repository to your GitHub account.

Keep Updated

If you already have a fork, ensure it’s up to date with the latest changes from the main repository.

Clone

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/ic.git
cd ic

2. Set Up Development Environment

System Requirements

Architecture: x86-64
Memory: Minimum 16 GB RAM/SWAP
Disk: 100 GB available space
OS: Ubuntu 22.04 or newer
Container Runtime: Podman

Enter Dev Container

# Use the provided dev container for consistent environment
./ci/container/container-run.sh

Alternatively, use the Dev Containers VS Code extension.

3. Local Testing

Before submitting your PR, run tests locally to avoid long feedback loops:

Quick Check
Unit Tests
Bazel Tests

# Run linting
./ci/scripts/rust-lint.sh

# Or run individual linting tools
cargo clippy --all-targets --all-features
cargo fmt --check

# Run tests with Cargo
cargo test

# Run tests for specific package
cargo test -p ic-consensus

# Run all tests except system tests
bazel test //... --test_tag_filters=-system_test

# Run specific test target
bazel test //rs/consensus:consensus_test

For more detailed testing instructions, see the HACKING.md document.

Submitting a Pull Request

Protected Files

For security reasons, external contributors cannot modify certain files. PRs that change these files will be closed automatically.

Refer to .github/repo_policies/EXTERNAL_CONTRIB_BLACKLIST for the list of protected files.

PR Workflow

Create Branch

Create a feature branch for your changes:

git checkout -b feature/my-feature

Make Changes

Implement your changes following the coding standards outlined below.

Commit Changes

Write clear, descriptive commit messages:

git add .
git commit -m "feat: add new consensus optimization"

Push to Fork

git push origin feature/my-feature

Open Pull Request

Navigate to your fork on GitHub
Click “New Pull Request”
Provide a clear title and description
Mark the PR as “Ready for Review”

PR Description Template

Provide a comprehensive PR description:

## Summary

Brief description of what this PR does.

## Motivation

Why is this change needed? What problem does it solve?

## Changes

- List key changes
- Include technical details
- Mention any breaking changes

## Testing

- How was this tested?
- What test cases were added?
- Any manual testing steps?

## Related Issues

Fixes #123
Related to #456

CI/CD Process for External Contributors

Security Restrictions

CI does not run automatically on PRs from external contributors for security reasons.

How CI Works

Initial Review

A maintainer will review your PR for security and quality.

Manual CI Trigger

After review, a maintainer will manually trigger CI for your PR.

CI Notification

You’ll receive a comment with a link to the CI run.

Results

Once CI completes, results will be reported back to your PR.

Subsequent Commits

Any new commits you push will require manual CI triggering again.

CI Pipeline

The CI pipeline runs:

Code formatting checks (rustfmt)
Linting (clippy)
Unit tests
Integration tests
Bazel build verification
System tests (for internal changes)

Coding Standards

Rust Style Guide

The project uses standard Rust formatting and linting tools:

Formatting

Use rustfmt with the project’s rustfmt.toml configuration
Run cargo fmt before committing
Line length limit defined in rustfmt.toml

Linting

Use clippy with the project’s clippy.toml configuration
Address all clippy warnings
Run cargo clippy --all-targets --all-features

Documentation

Document all public APIs with doc comments
Include examples in doc comments where appropriate
Add module-level documentation explaining purpose and design

Testing

Write unit tests for new functionality
Add integration tests for cross-component features
Ensure tests are deterministic and reproducible

Code Organization

Keep modules focused - Each module should have a single, clear purpose
Use appropriate visibility - Mark items as pub only when necessary
Follow naming conventions - Use snake_case for functions/variables, PascalCase for types
Minimize dependencies - Only add necessary external crates

Dependency Management

When adding external crate dependencies, follow these rules:

Verify necessity - Ensure the crate is truly needed
- Check if similar functionality exists in already-imported crates
- Confirm the crate is well-maintained and from reputable authors
Maintain consistency - Use workspace dependencies
- Add new crates to [workspace.dependencies] in root Cargo.toml
- Reference with new-crate = { workspace = true } in package Cargo.toml
Avoid version fragmentation - When bumping dependencies, update across the entire repository
Keep toolchain updated - Maintain rust-lang versions for both Bazel and Cargo

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.28", features = ["full"] }

Review Process

What Reviewers Look For

Timeline Expectations

Initial review: Within 1-2 weeks for most PRs
Follow-up reviews: Within a few days for revisions
Merging: After all reviewers approve and CI passes

Large or complex PRs may take longer to review. Consider breaking large changes into smaller, incremental PRs.

Addressing Review Feedback

Respond to comments - Acknowledge feedback and explain your approach
Make requested changes - Update your code based on reviewer suggestions
Ask questions - If feedback is unclear, ask for clarification
Push updates - Push new commits to your PR branch (don’t force-push unless requested)

Building the Project

Quick Build Commands

Full Build
Binaries Only
Replica
Bazel

# Build all IC-OS images in containerized environment
./ci/container/build-ic.sh -i

# Artifacts located in: artifacts/

# Build binaries and canisters
./ci/container/build-ic.sh -b -c

# Build replica with Cargo
cd rs
cargo build --release --bin replica

# Build with Bazel
bazel build //rs/replica

# Build IC-OS images
bazel build //ic-os/guestos/envs/dev/...

Open Source Licensing

All code in the Internet Computer repository is licensed under:

Apache 2.0 - Most components
IC Community Source License - Certain restrictive components (see licenses/IC-1.0.txt)
IC Shared Community Source License - Certain shared components (see licenses/IC-shared-1.0.txt)

The more restrictive licenses protect the Intellectual Property of the DFINITY Foundation while enabling community review and verification.

Getting Help

Forum

Ask questions and discuss ideas

HACKING.md

Quick reference for common tasks

Security Policy

Report security vulnerabilities

Testing Guide

Learn about testing infrastructure

Community Standards

Code of Conduct

We expect all contributors to:

Be respectful and inclusive
Provide constructive feedback
Focus on what’s best for the community
Show empathy towards others

Communication Channels

Forum: forum.dfinity.org - General discussions, questions, and announcements
GitHub Issues: Bug reports and feature requests
Pull Requests: Code contributions and technical discussions

Workspace Structure

Understand the monorepo organization

Testing

Comprehensive testing guide

Security

Security policy and reporting

Overview

Getting Started

Architecture

Core Components

IC-OS

Chain Integration

Development

​Before You Start

​Contribution License Agreement

​Getting Started

​1. Fork the Repository

​2. Set Up Development Environment

​System Requirements

​Enter Dev Container

​3. Local Testing

​Submitting a Pull Request

​Protected Files

​PR Workflow

​PR Description Template

​CI/CD Process for External Contributors

​Security Restrictions

​How CI Works

​CI Pipeline

​Coding Standards

​Rust Style Guide

​Code Organization

​Dependency Management

​Review Process

​What Reviewers Look For

​Timeline Expectations

​Addressing Review Feedback

​Building the Project

​Quick Build Commands

​Open Source Licensing

​Getting Help

Forum

HACKING.md

Security Policy

Testing Guide

​Community Standards

​Code of Conduct

​Communication Channels

​Related Resources

Workspace Structure

Testing

Security

Build docs developers (and LLMs) love

Before You Start

Contribution License Agreement

Getting Started

1. Fork the Repository

2. Set Up Development Environment

System Requirements

Enter Dev Container

3. Local Testing

Submitting a Pull Request

Protected Files

PR Workflow

PR Description Template

CI/CD Process for External Contributors

Security Restrictions

How CI Works

CI Pipeline

Coding Standards

Rust Style Guide

Code Organization

Dependency Management

Review Process

What Reviewers Look For

Timeline Expectations

Addressing Review Feedback

Building the Project

Quick Build Commands

Open Source Licensing

Getting Help

Community Standards

Code of Conduct

Communication Channels

Related Resources