Contributing

Welcome to NVIDIA FLARE! We’re excited you’re here and want to contribute. This documentation is intended for individuals and institutions interested in contributing to NVIDIA FLARE. NVIDIA FLARE is an open-source project and, as such, its success relies on its community of contributors willing to keep improving it. Your contribution will be a valued addition to the code base; we simply ask that you read this page and understand our contribution process, whether you are a seasoned open-source contributor or whether you are a first-time contributor.

Communicate with us

We are happy to talk with you about your needs for NVIDIA FLARE and your ideas for contributing to the project. One way to do this is to create an issue discussing your thoughts. It might be that a very similar feature is under development or already exists, so an issue is a great starting point.

The contribution process

Pull request early

We encourage you to create pull requests early. It helps us track the contributions under development, whether they are ready to be merged or not. Change your pull request’s title, to begin with [WIP] and/or create a draft pull request until it is ready for formal review.

Preparing pull requests

To ensure the code quality, NVIDIA FLARE relies on several linting tools (flake8 and its plugins, black and isort)

This section highlights all the necessary preparation steps required before sending a pull request. To collaborate efficiently, please read through this section and follow them.

Checking the coding style

We check code style using flake8 and isort. A bash script (runtest.sh) is provided to run all tests locally.

License information: all source code files should start with this paragraph:

# Copyright (c) 2021-2022, NVIDIA CORPORATION.  All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Unit testing

NVIDIA FLARE tests are located under tests/. The unit test file names follow the [module_name]_test.py pattern.

The bash script runtest.sh will run unit tests also.

Building the documentation

Use a dedicated documentation environment to preserve training dependencies. From the repository root, create and activate a new environment, then build:

python3.10 -m venv .venv-docs
source .venv-docs/bin/activate
./build_doc.sh --html

The script installs the documentation dependencies. Linux x86_64 with Python 3.10 uses the same pinned CPU framework environment as Read the Docs; other supported environments use the documentation extra. Keep this environment separate from the development or training environment.

For a quick preview of narrative pages, omit the generated Python API reference:

./build_doc.sh --html --skip-api

This mode installs only Sphinx and its documentation extensions. The API landing page and Python cross-references are incomplete, so use the full build before publishing or reviewing API documentation.

Open docs/_build/index.html to read the generated HTML. To clean generated files:

./build_doc.sh --clean

The production dependency pins are in docs/constraints.txt. Update them in a fresh documentation environment and verify the full HTML and Markdown build before committing new versions.

Signing your work

NVIDIA FLARE enforces the Developer Certificate of Origin (DCO) on all pull requests.

For a detailed guide on signing commits, please see Signing commits from GitHub.

Commit signature verification

NVIDIA FLARE enforces commit signature verification, a security feature provided by GitHub. Developers are required to setup GPG keys as described in Commit Signature Verification.

Full text of the DCO:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Submitting pull requests

All code changes to the main branch must be done via pull requests.

Pull requests from external contributors (contributors without write, maintain, or admin access to NVIDIA/NVFlare) must reference an existing GitHub issue in NVIDIA/NVFlare that describes the problem or proposed improvement, explains why the change is needed, and provides supporting evidence where applicable. The issue must exist before the pull request is submitted, and the proposed changes must directly address it. Pull requests from external contributors without a qualifying issue will not be accepted.

Repository collaborators with write, maintain, or admin access may submit pull requests without a GitHub issue. Every pull request must describe the problem or proposed improvement and explain why the change is needed.

1. For external contributions, create a new ticket or take a known ticket from the issue list. 2. If the task has not been taken, create a new branch in your fork of the codebase. Ideally, the new branch should be based on the latest main branch. 3. Make changes to the branch (use detailed commit messages if possible). 4. Make sure that new tests cover the changes and the changed codebase passes all tests locally. 5. Create a new pull request from the task branch to the main branch, with detailed descriptions of the purpose of this pull request. 6. Check the CI/CD status of the pull request, make sure all CI/CD tests passed. 7. Wait for reviews; if there are reviews, make point-to-point responses, make further code changes if needed. 8. If there are conflicts between the pull request branch and the main branch, pull the changes from main and resolve the conflicts locally. 9. Reviewer and contributor may have discussions back and forth until all comments addressed. All conversations must be resolved for PR to pass. 10. Wait for the pull request to be merged.

Pull request description guidance

Every pull request must explain what changes, why the change is needed, and how it was validated. Include validation commands and results, and state anything that could not be verified. Scale the detail to the scope and impact of the change, rather than the number of changed lines. Use the relevant categories below; a pull request may span more than one category. Link existing design documents where useful and summarize the key decisions in the PR description.

  • Small bug fix: Describe the problem, root cause, fix approach, and regression test or verification.

  • Complex bug fix: Include a reproduction scenario, root cause, overall fix approach, changes across affected modules, compatibility risks, and regression coverage.

  • Feature enhancement: Explain the motivation, design, workflow, risks, validation, and documentation updates. Include architecture and alternatives considered with their tradeoffs where relevant.

  • FL algorithm implementation: Include paper references where applicable, the main research idea, implementation design and workflow, and deviations from the paper. Apply the relevant feature enhancement guidance, including architecture, alternatives, and risks. Describe the experiment setup, results, and limitations, and provide a runnable example and User Guide.

  • FL algorithm / research example: Include paper references where applicable, the main research idea, and experiment approach. Provide a README covering dependencies, setup, data preparation, execution commands, expected results, and limitations.

  • Documentation, refactoring, dependency, or tooling change: Briefly describe the purpose, affected areas, and relevant validation. Explain behavior or compatibility changes, if any.

Benchmarks are optional for algorithm implementations and research examples unless needed to support performance claims. Include architecture and alternatives sections where relevant to the change; a small fix does not need a separate design document.

Reviewing pull requests

For pull requests from external contributors, verify that the linked GitHub issue exists, predates the pull request, and is directly addressed by the proposed changes before reviewing the code. For every pull request, maintainers must confirm that the proposed changes address a valid problem or an improvement appropriate for the project before approving it.

All code review comments should be specific, constructive, and actionable. 1. Check the CI/CD status of the pull request, make sure all CI/CD tests passed before reviewing (contact the branch owner if needed). 1. Read carefully the descriptions of the pull request and the files changed, write comments if needed. 1. Make in-line comments to specific code segments, request for changes if needed. 1. Review any further code changes until all comments addressed by the contributors. 1. Merge the pull request to the main branch. 1. Close the corresponding task ticket on the issue list, if applicable.