Skip to content

Latest commit

 

History

History
199 lines (127 loc) · 8.55 KB

CONTRIBUTING.md

File metadata and controls

199 lines (127 loc) · 8.55 KB
Raw

Contributing to cuGraph

cuGraph, and all of RAPIDS in general, is an open-source project where we encourage community involvement. There are multiple ways to be involved and contribute to the cuGraph community, the top paths are listed below:

If you are ready to contribute, jump right to the Contribute Code section.

Style Formatting Tools:

  • clang-format version 8.01+
  • flake8 version 3.5.0+
  • black version 22.3.0

1) File an Issue for the RAPIDS cuGraph team to work

To file an issue, go to the RAPIDS cuGraph issue page an select the appropriate issue type. Once an issue is filed the RAPIDS cuGraph team will evaluate and triage the issue. If you believe the issue needs priority attention, please include that in the issue to notify the team.

Bug Report If you notice something not working please file an issue

  • Select Bug Report
  • Describing what you encountered and the severity of the issue: Does code crash or just not return the correct results
  • Include a sequence of step to reproduce the error

Propose a new Feature or Enhancement If there is a feature or enhancement to an existing feature, please file an issue

  • Select either Enhancement Request or Feature Report
  • describing what you want to see added or changed. For new features, if there is a white paper on the analytic, please include a reference to it

Ask a Question There are several ways to ask questions, including Stack Overflow or the RAPIDS Google forum, but a GitHub issue can be filled.

  • Select Question
  • describing your question

2) Propose a New Feature and Implement It

We love when people want to get involved, and if you have a suggestion for a new feature or enhancement and want to be the one doing the development work, we fully encourage that.

  • Submit a New Feature Issue (see above) and state that you are working on it.
  • The team will give feedback on the issue and happy to make suggestions
  • Once we agree that the plan looks good, go ahead and implement it
  • Follow the code contributions guide below.

3) You want to implement a feature or bug-fix for an outstanding issue

  • Find an open Issue, and post that you would like to work that issues
  • Once we agree that the plan looks good, go ahead and implement it
  • Follow the code contributions guide below.

If you need more context on a particular issue, please ask.

So you want to contribute code

TL;DR General Development Process

  1. Read the documentation on building from source to learn how to setup, and validate, the development environment
  2. Read the RAPIDS Code of Conduct
  3. Find or submit an issue to work on (include a comment that you are working issue)
  4. Fork the cuGraph repo and Code (make sure to add unit tests)!
  5. When done, and code passes local CI, create your pull request (PR)
    1. Update the CHANGELOG.md with PR number - see Changelog formatting
    2. Ensure that the PR has the proper tags
    3. Ensure the code matches out style guide
  6. Verify that cuGraph CI passes all status checks. 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!

The FIXME comment

Use the FIXME comment to capture technical debt. It should not be used to flag bugs since those need to be cleaned up before code is submitted.
We are implementing a script to count and track the number of FIXME in the code. Usage of TODO or any other tag will not be accepted.

Fork a private copy of cuGraph

The RAPIDS cuGraph repo cannot directly be modified. Contributions must come in the form of a Pull Request from a forked version of cugraph. GitHub as a nice write up ion the process: https://help.github.com/en/github/getting-started-with-github/fork-a-repo

  1. Fork the cugraph repo to your GitHub account
  2. clone your version git clone https://github.com/<YOUR GITHUB NAME>/cugraph.git

Read the section on building cuGraph from source to validate that the environment is correct.

Pro Tip add an upstream remote repository so that you can keep your forked repo in sync git remote add upstream https://github.com/rapidsai/cugraph.git

  1. Checkout the latest branch cuGraph only allows contribution to the current branch and not main or a future branch. Please check the cuGraph page for the name of the current branch.

git checkout branch-x.x

  1. Code .....
  2. Once your code works and passes tests
    1. commit your code git push
  3. From the GitHub web page, open a Pull Request
    1. follow the Pull Request tagging policy

Development Environment

There is no recommended or preferred development environment. There are a few must have conditions on GPU hardware and library versions. But for the most part, users can work in the environment that they are familiar and comfortable with.

Hardware

  • You need to have accesses to an NVIDIA GPU that is Pascal or later.

IDEs

There is no recommended IDE, here is just a list of what cuGraph developers currently use (not in any priority order)

  • NSIGHT
  • Eclipse (with the C++ and Python modules)
  • VSCode
  • VIM / VI (old school programming)
    • With plug-ins like FZF, Rg

Using VSCode, you can develop remotely from the hardware if you so wish. Alex Fender has a setting up remote development: https://github.com/afender/cugraph-vscode

Debug

  • cuda-memcheck
  • cuda-gdb

A debug launch can also be enabled in VSCode with something like: https://github.com/harrism/cudf-vscode/blob/master/.vscode/launch.json

Seasoned developers

Once you have gotten your feet wet and are more comfortable with the code, you can look at the prioritized issues of our next release in our project boards.

Pro Tip: Always look at the release board with the lowest number for issues to work on. This is where RAPIDS developers also focus their efforts. cuGraph maintains a project board for the current release plus out two future releases. This allows to better long term planning

Look at the unassigned issues, and find an issue you are comfortable with contributing to. Start with Step 3 from above, commenting on the issue to let others know you are working on it. If you have any questions related to the implementation of the issue, ask them in the issue instead of the PR.

Style Guide

All Python code most pass flake8 and black style checking; see using pre-commit below.

All C++ code must pass clang style checking

All code must adhere to the RAPIDS Style Guide

Python / Pre-commit hooks

cuGraph developers may use pre-commit to locally run code linters and formatters including Black and flake8. These tools ensure a consistent code format throughout the project. Using pre-commit ensures that linter versions and options are aligned for all developers. Additionally, there is a CI check in place to enforce that committed code follows our standards.

To use pre-commit, install via conda or pip:

conda install -c conda-forge pre-commit
pip install pre-commit

Then run pre-commit hooks before committing code:

pre-commit run

Optionally, you may set up the pre-commit hooks to run automatically when you make a git commit. This can be done by running:

pre-commit install

Now code linters and formatters will be run each time you commit changes.

You can skip these checks with git commit --no-verify or with the short version git commit -n.

Tests

All code must have associate test cases. Code without test will not be accepted