Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
203 lines (150 loc) · 8.42 KB

CONTRIBUTING.md

File metadata and controls

203 lines (150 loc) · 8.42 KB
Raw

Contributing to nx-cugraph

If you are interested in contributing to nx-cugraph, your contributions will fall into three categories:

  1. You want to report a bug, feature request, or documentation issue
    • File an issue describing what you encountered or what you want to see changed.
    • Please run and paste the output of the print_env.sh script while reporting a bug to gather and report relevant environment details.
    • The RAPIDS team will evaluate the issues and triage them, scheduling them for a release. If you believe the issue needs priority attention, comment on the issue to notify the team.
  2. You want to propose a new Feature and implement it
    • Post about your intended feature, and we shall discuss the design and implementation.
    • Once we agree that the plan looks good, go ahead and implement it, using the code contributions guide below.
  3. You want to implement a feature or bug-fix for an outstanding issue
    • Follow the code contributions guide below.
    • If you need more context on a particular issue, please ask and we shall assist.

Code Contributions

Your First Issue

  1. Read the project's README.md to learn how to setup the development environment. # FIXME ADD THIS SECTION
  2. Find an issue to work on. Issues or help wanted labels
  3. Comment on the issue saying you are going to work on it.
  4. Code! Make sure to update unit tests!
  5. When done, create your pull request.
  6. Verify that CI passes all status checks, or fix if needed.
  7. Wait for other developers to review your code and update code as needed.
  8. Once reviewed and approved, a RAPIDS developer will merge your pull request.

Remember, if you are unsure about anything, don't hesitate to comment on issues and ask for clarifications!

Building and Installing From Source

These instructions are tested on supported versions/distributions of Linux, CUDA, and Python - See RAPIDS Getting Started for the list of supported environments. Other environments might be compatible, but are not currently tested. Further details about requirements are described in the RAPIDS System Requirements page.

Create the build environment

  • Clone the repository:
git clone https://github.com/rapidsai/nx-cugraph.git
cd nx-cugraph

Create conda environment and install dependencies

# for CUDA 13 environments
conda env create --name nxcg-dev --file conda/environments/all_cuda-133_arch-$(uname -m).yaml

# activate the environment
conda activate nxcg-dev
  • Note: the conda environment files are updated frequently, so the development environment may also need to be updated if dependency versions or pinnings are changed.

Build nx-cugraph from source

# for details and usage, run with the --help flag
./build.sh
  • Note: if Python files (*.py) have changed, the build must be rerun.

To verify your install with tests, run

pytest -v nx_cugraph/tests

Code Formatting

Consistent code formatting is important in the nx-cugraph project to ensure readability, maintainability, and thus simplifies collaboration.

Using pre-commit hooks

nx-cugraph uses pre-commit to execute code linters and formatters that check the code for common issues, such as syntax errors, code style violations, and help to detect bugs. Using pre-commit ensures that linter versions and options are aligned for all developers. The same hooks are executed as part of the CI checks. This means running pre-commit checks locally avoids unnecessary CI iterations.

To use pre-commit, install the tool via conda or pip into your development environment:

conda install -c conda-forge pre-commit

Alternatively:

pip install pre-commit

After installing pre-commit, it is recommended to install pre-commit hooks to run automatically before creating a git commit. In this way, it is less likely that style checks will fail as part of CI checks. To install pre-commit hooks, simply run the following command within the repository root directory:

pre-commit install

By default, pre-commit runs on staged files only, meaning only on changes that are about to be committed. To run pre-commit checks on all files, execute:

pre-commit run --all-files

To skip the checks temporarily, use git commit --no-verify or its short form -n.

Note: If the auto-formatters' changes affect each other, you may need to go through multiple iterations of git commit and git add -u.

Summary of pre-commit hooks

The pre-commit hooks configured for this repository consist of a number of linters and auto-formatters that we summarize here. For a full and current list, please see the .pre-commit-config.yaml file.

Managing PR labels

Each PR must be labeled according to whether it is a "breaking" or "non-breaking" change (using Github labels). This is used to highlight changes that users should know about when upgrading.

For nx-cugraph, a "breaking" change is one that modifies the public, non-experimental, Python API in a non-backward-compatible way.

Additional labels must be applied to indicate whether the change is a feature, improvement, bugfix, or documentation change. See the shared RAPIDS documentation for these labels: https://github.com/rapidsai/kb/issues/42.

Branches and Versions

The nx-cugraph repository has two main branches:

  1. main branch: primary development for the next release
  2. release/YY.MM (e.g. release/26.02): release branch for a given release. Once that release is completed, only hotfixes should be targeted at this branch.

Additional details

For all development, your changes should be pushed into a branch (created using the naming instructions below) in your own fork of nx-cugraph and then create a pull request when the code is ready.

PRs should target main by default, except in the following situations:

  • changes target a soon-to-be-released version: release/YY.MM
  • hotfixes targeting critical issues: hotfix/YY.MM.patch-version

For more details, see https://docs.rapids.ai/releases/process/

Branch naming

Branches used to create PRs should have a name of the form <type>-<name> which conforms to the following conventions:

  • Type:
    • fea - For if the branch is for a new feature(s)
    • enh - For if the branch is an enhancement of an existing feature(s)
    • bug - For if the branch is for fixing a bug(s) or regression(s)
  • Name:
    • A name to convey what is being worked on
    • Please use dashes or underscores between words as opposed to spaces.

Attribution

Portions adopted from https://github.com/pytorch/pytorch/blob/master/CONTRIBUTING.md