Contributing

FBOSS accepts pull requests on GitHub. This page summarizes the contribution process, the development setup, the checks a change must pass (pre-commit hooks, copyright headers, generated files), the tests you can run without hardware, the CI workflows, and the repository conventions.

Process

  1. Fork the repository and create a branch. CONTRIBUTING.md says to branch from master, but the default branch is main.
  2. Add tests for new code and update documentation when you change APIs.
  3. Make sure the tests pass and the code lints.
  4. Sign Meta's Contributor License Agreement (CLA) once, at the link in CONTRIBUTING.md.
  5. Open the pull request.

Bugs go to GitHub Issues with clear reproduction steps; questions to Issues or Discussions. Security bugs go through Meta's bug bounty program, not a public issue. Contributions are licensed under the project's BSD license.

Development Setup

Develop in the same container used for builds (see Building FBOSS):

sudo docker build . -t fboss_image -f fboss/oss/docker/Dockerfile
sudo docker run -d -it --name=FBOSS_BUILD_CONTAINER -v $PWD:/var/FBOSS/fboss:z fboss_image:latest bash
sudo docker exec -it FBOSS_BUILD_CONTAINER bash
cd /var/FBOSS/fboss
./fboss/oss/scripts/run-getdeps.py build --allow-system-packages \
  --scratch-path /var/FBOSS/tmp_bld_dir --src-dir . --cmake-target <target> fboss

Always build with --src-dir . so your changes are compiled, and with --cmake-target to keep iterations short (for example fboss2_targets for CLI work, qsfp_targets, or fboss_platform_services). For agent and CLI work without a switch, use the fake SAI build and the fboss-sim container from the Quick Start.

Pre-commit Hooks

The repository uses pre-commit. Install the development requirements (requirements-dev.txt: pre-commit, jsonschema) and the hooks:

pip install -r requirements-dev.txt
pre-commit install
pre-commit run --all-files

Hooks configured in .pre-commit-config.yaml (everything under build/ is excluded):

Hook Scope
clang-format (--style=file) C and C++
shellcheck (-x --severity=warning) and shfmt (-w -s -i 2) Shell scripts
trailing-whitespace, end-of-file-fixer, check-merge-conflict All files
check-yaml, check-json YAML and JSON (generated ASIC configs excluded)
ruff-check --fix, ruff-format Python under fboss/
fboss-copyright-headers New C/C++ files under fboss/
do-not-change-fboss-manifests Rejects staged changes adding sai_impl to build/fbcode_builder/manifests/fboss, a common mistake with git commit -a after an SDK build

A BUCK/CMake file-list consistency checker (fboss/oss/scripts/buck_cmake_dep_checker.py) exists but is commented out in the hook config until existing violations are fixed. If you add source files, keep the CMake lists in cmake/ in sync with the BUCK files anyway.

Code Style and Conventions

  • C++: 2-space indentation, 80-character lines, cuddled braces; follow the surrounding code. .clang-format encodes the details.
  • Every file ends with a newline and uses Unix line endings.

  • New C and C++ files start with the canonical notice, without a year:

    // Copyright (c) Meta Platforms, Inc. and affiliates.

    This applies to external contributors as well. Keep existing notices in generated, vendored, and third-party code, and never add Confidential and proprietary notices.

  • Never edit files marked @generated. Thrift files generate code: regenerate rather than editing the output.

  • Platform mappings: edit the CSVs in fboss/configs/platforms/<vendor>/<platform>/platform_mapping/ and regenerate; never edit generated/. See Platform Support.

Tests You Can Run Without Hardware

Kind Examples
Unit tests transceiver_manager_test, transceiver_state_machine_test, cmis_test, fboss2_cmd_test, fboss2_framework_test, sensor_service_sw_test, fan_service_sw_test, platform_manager_*_test, weutil_*_test
Fake SAI agent tests sai_test-fake, sai_agent_hw_test-fake, multi_switch_agent_hw_test, sai_agent_scale_test-fake, sai_invariant_agent_test-fake, switch_test (target fboss_fake_agent_test_targets)
CLI integration fboss2_integration_test in the fboss-sim container
Run-script unit tests Python tests for run_test.py under fboss/oss/scripts/run_scripts/fboss_test_runner/unittests/

Anything named *_hw_test, or sai_test built against a real SDK, needs a switch. Known-bad and unsupported lists live under fboss/oss/; if your change fixes or breaks a hardware test on some ASIC, update the corresponding list.

CI

GitHub Actions workflows in .github/workflows/ include:

Workflow Checks
pre-commit.yml The pre-commit hooks
agent.yml, qsfp-build.yml, fsdb.yml, platform-services.yml, fboss2-cli.yml Builds and tests of each component
platform-mapping-verification.yml Generated platform mappings match their CSV inputs
agent-config-generation-verification.yml Generated agent configs are current
run-scripts-unittests.yml run_test.py unit tests
distro_image_build.yml Distro image build
export-centos-docker-image.yml, export-debian-docker-image.yml Publish the build container images
github-pages-deploy.yml, github-pages-test-deploy.yml The project's documentation site from docs/

Documentation

The project's own documentation is a Docusaurus site in docs/ (Markdown in docs/docs/, runnable command snippets in docs/static/code_snips/). Update it alongside behavior changes.

Not in the Open Source Repository

The Buck build, Meta-internal configuration, internal test infrastructure, and internal CI are not part of this repository. Code comments and documents that refer to them (for example facebook/ subdirectories, buck2 commands, or #ifndef IS_OSS blocks) apply only to internal checkouts.

Workflow Guides for Coding Agents

fboss/skills/ contains task-specific workflow guides intended for AI coding agents (and readable by humans): debugging agent hardware, link, and QSFP test failures, onboarding agents and transceivers, applying FBOSS coding standards, reviewing changes, building locally, adding config CLI commands, platform services, and distro images. AGENTS.md at the repository root points to them.

See Also