Skip to content

Commit

Permalink
more docs updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@BradReesWork
BradReesWork committed Apr 17, 2020
1 parent 762c024 commit dc5d397
Show file tree
Hide file tree
Showing 3 changed files with 85 additions and 240 deletions.
313 changes: 74 additions & 239 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,292 +1,127 @@
# 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 three paths are listed below:

If you are interested in contributing to cuGraph, your contributions will fall
into three categories:
1. You want to report a bug, feature request, or documentation issue
- File an [issue](https://github.com/rapidsai/cugraph/issues/new/choose)
describing what you encountered or what you want to see changed.
- 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](#code-contributions) guide below.
3. You want to implement a feature or bug-fix for an outstanding issue
- Follow the [code contributions](#code-contributions) guide below.
- If you need more context on a particular issue, please ask and we shall
provide.

## Code contributions

### Your first issue

1. Read the project's [README.md](https://github.com/rapidsai/cugraph/blob/master/README.md)
to learn how to setup the development environment
2. Find an issue to work on. The best way is to look for the [good first issue](https://github.com/rapidsai/cugraph/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
or [help wanted](https://github.com/rapidsai/cugraph/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) labels
3. Comment on the issue saying you are going to work on it
4. Fork the cuGraph repo and Code! Make sure to update unit tests!
5. When done, [create your pull request](https://github.com/rapidsai/cugraph/compare)
6. Verify that CI passes all [status checks](https://help.github.com/articles/about-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!

### 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](https://github.com/rapidsai/cugraph/projects).

> **Pro Tip:** Always look at the release board with the highest number for
issues to work on. This is where RAPIDS developers also focus their efforts.

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.

## Setting Up Your Build Environment

### Build from Source

The following instructions are for developers and contributors to cuGraph OSS development. These instructions are tested on Linux Ubuntu 16.04 & 18.04. Use these instructions to build cuGraph from source and contribute to its development. Other operating systems may be compatible, but are not currently tested.

The cuGraph package include both a C/C++ CUDA portion and a python portion. Both libraries need to be installed in order for cuGraph to operate correctly.

The following instructions are tested on Linux systems.

#### Prerequisites

Compiler requirement:

* `gcc` version 5.4+
* `nvcc` version 10.0+
* `cmake` version 3.12
#### 1) Filing in Issue for the RAPIDS cuGraph team to work

CUDA requirement:
***Bug Report***
If you notice something not working please file an issue

* CUDA 10.0+
* NVIDIA driver 396.44+
* Pascal architecture or better
- File an [issue](https://github.com/rapidsai/cugraph/issues/new/choose)
- 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
- The RAPIDS 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.

You can obtain CUDA from [https://developer.nvidia.com/cuda-downloads](https://developer.nvidia.com/cuda-downloads).
***Propose a new Feature or Enhancement***
If there is a feature or enhancement to an existing feature, please file an issue

#### Build and Install the C/C++ CUDA components
- File an [issue](https://github.com/rapidsai/cugraph/issues/new/choose)
- 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
- The RAPIDS team will evaluate and triage the issue, and then schedule it in a future release.
- If you believe the issue needs priority attention, please include that in
the issue to notify the team.

To install cuGraph from source, ensure the dependencies are met and follow the steps below:
***Ask a Question***
There are several ways to ask questions, including [Stack Overflow]( https://stackoverflow.com/) or the RAPIDS [Google forum]( https://groups.google.com/forum/#!forum/rapidsai), but an GitHub issue can be filled.

1) Clone the repository
- File an [issue](https://github.com/rapidsai/cugraph/issues/new/choose)
- Select Question
- describing your question
- The RAPIDS team will attempt to answer your question as quick as possible

```bash
# Set the localtion to cuGraph in an environment variable CUGRAPH_HOME
export CUGRAPH_HOME=$(pwd)/cugraph

# Download the cuGraph repo
git clone https://github.com/rapidsai/cugraph.git $CUGRAPH_HOME
#### 2) Propose a New Feature and Implement It

cd $CUGRAPH_HOME
```
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.

2) Create the conda development environment

```bash
# create the conda environment (assuming in base `cugraph` directory)

# for CUDA 10
conda env create --name cugraph_dev --file conda/environments/cugraph_dev_cuda10.0.yml

# for CUDA 10.1
conda env create --name cugraph_dev --file conda/environments/cugraph_dev_cuda10.1.yml

# for CUDA 10.2
conda env create --name cugraph_dev --file conda/environments/cugraph_dev_cuda10.2.yml

# activate the environment
conda activate cugraph_dev

# to deactivate an environment
conda deactivate
```

- The environment can be updated as development includes/changes the dependencies. To do so, run:


```bash

# for CUDA 10
conda env update --name cugraph_dev --file conda/environments/cugraph_dev_cuda10.0.yml

# for CUDA 10.1
conda env update --name cugraph_dev --file conda/environments/cugraph_dev_cuda10.1.yml

# for CUDA 10.2
conda env update --name cugraph_dev --file conda/environments/cugraph_dev_cuda10.2.yml

conda activate cugraph_dev
```

3) Build and install `libcugraph`. CMake depends on the `nvcc` executable being on your path or defined in `$CUDACXX`.

This project uses cmake for building the C/C++ library. CMake will also automatically build and install nvGraph library (`$CUGRAPH_HOME/cpp/nvgraph`) which may take a few minutes. To configure cmake, run:
- 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, using
the [code contributions](#code-contributions) guide below.

```bash
# Set the localtion to cuGraph in an environment variable CUGRAPH_HOME
export CUGRAPH_HOME=$(pwd)/cugraph

cd $CUGRAPH_HOME
cd cpp # enter cpp directory
mkdir build # create build directory
cd build # enter the build directory
cmake .. -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX
#### 3) You want to implement a feature or bug-fix for an outstanding issue
- Follow the [code contributions](#code-contributions) guide below.

# now build the code
make -j # "-j" starts multiple threads
make install # install the libraries
```
The default installation locations are `$CMAKE_INSTALL_PREFIX/lib` and `$CMAKE_INSTALL_PREFIX/include/cugraph` respectively.
If you need more context on a particular issue, please ask.

As a convenience, a `build.sh` script is provided in `$CUGRAPH_HOME`. To execute the same build commands above, run the script as shown below. Note that the libraries will be installed to the location set in `$PREFIX` if set (i.e. `export PREFIX=/install/path`), otherwise to `$CONDA_PREFIX`.
```bash
$ cd $CUGRAPH_HOME
$ ./build.sh libcugraph # build the cuGraph libraries and install them to
# $PREFIX if set, otherwise $CONDA_PREFIX
```

#### Building and installing the Python package
# So You Want to Contribute Code

5. Install the Python package to your Python path:
### TL;DR General Development Process

```bash
cd $CUGRAPH_HOME
cd python
python setup.py build_ext --inplace
python setup.py install # install cugraph python bindings
```
1. Read the documentation on [building from source](SOURCEBUILD.md) to learn how to setup, and validate, the development environment
2. Find an issue, or submit an issue, to work on.
3. Comment on the issue saying you are going to work on it
4. Fork the cuGraph [repo](#fork) and Code (make sure to add unit tests)!
5. When done, and code passes local CI, create your pull request (PR)
6. Verify that CI passes all [status checks](https://help.github.com/articles/about-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

Like the `libcugraph` build step above, `build.sh` can also be used to build the `cugraph` python package, as shown below:
```bash
$ cd $CUGRAPH_HOME
$ ./build.sh cugraph # build the cuGraph python bindings and install them
# to $PREFIX if set, otherwise $CONDA_PREFIX
```
Remember, if you are unsure about anything, don't hesitate to comment on issues
and ask for clarifications!

Note: other `build.sh` options include:
```bash
$ cd $CUGRAPH_HOME
$ ./build.sh clean # remove any prior build artifacts and configuration (start over)
$ ./build.sh libcugraph -v # compile and install libcugraph with verbose output
$ ./build.sh libcugraph -g # compile and install libcugraph for debug
$ PARALLEL_LEVEL=4 ./build.sh libcugraph # compile and install libcugraph limiting parallel build jobs to 4 (make -j4)
$ ./build.sh libcugraph -n # compile libcugraph but do not install
```

#### Run tests

6. Run either the C++ or the Python tests with datasets
### Fork a private copy of cuGraph that can we modified
<a name="fork"></a>

- **Python tests with datasets**
The RAPIDS cuGraph repo cannot directly be modified. Contributions must come in the form of a *Pull Request* from a folked 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

```bash
cd $CUGRAPH_HOME
cd python
pytest
```
- **C++ stand alone tests**
Read the section on [building cuGraph from source](SOURCEBUILD.md) to validate that the environment is correct.

From the build directory :

```bash
# Run the cugraph tests
cd $CUGRAPH_HOME
cd cpp/build
gtests/GDFGRAPH_TEST # this is an executable file
```
- **C++ tests with larger datasets**
### Development Environment

If you already have the datasets:
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.

```bash
export RAPIDS_DATASET_ROOT_DIR=<path_to_ccp_test_and_reference_data>
```
If you do not have the datasets:
**Hardware**

```bash
cd $CUGRAPH_HOME/datasets
source get_test_data.sh #This takes about 10 minutes and download 1GB data (>5 GB uncompressed)
```
* You need to have accesses to an NVIDAI GPU that is Pascal or later.

Run the C++ tests on large input:

```bash
cd $CUGRAPH_HOME/cpp/build
#test one particular analytics (eg. pagerank)
gtests/PAGERANK_TEST
#test everything
make test
```
**IDEs**

Note: This conda installation only applies to Linux and Python versions 3.6/3.7.
There is no recommended IDE, here is just a list of what cuGraph developers currently use (not in any priority order)

### Building and Testing on a gpuCI image locally
* NSIGHT
* Eclipse (with the C++ and Python modules)
* VSCode
* VIM / VI (old school programming)
* With plug-ins like [FZF](https://github.com/junegunn/fzf), [Rg](https://github.com/BurntSushi/ripgrep)

Before submitting a pull request, you can do a local build and test on your machine that mimics our gpuCI environment using the `ci/local/build.sh` script.
For detailed information on usage of this script, see [here](ci/local/README.md).

### (OPTIONAL) Set environment variable on activation
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

It is possible to configure the conda environment to set environmental variables on activation. Providing instructions to set PATH to include the CUDA toolkit bin directory and LD_LIBRARY_PATH to include the CUDA lib64 directory will be helpful.

```bash
cd ~/anaconda3/envs/cugraph_dev
**Debug**

mkdir -p ./etc/conda/activate.d
mkdir -p ./etc/conda/deactivate.d
touch ./etc/conda/activate.d/env_vars.sh
touch ./etc/conda/deactivate.d/env_vars.sh
```
* cuda-memcheck

Next the env_vars.sh file needs to be edited

```bash
vi ./etc/conda/activate.d/env_vars.sh
A debug launch can also be enabled in VSCode with something like: https://github.com/harrism/cudf-vscode/blob/master/.vscode/launch.json

#!/bin/bash
export PATH=/usr/local/cuda-10.0/bin:$PATH # or cuda-10.2 if using CUDA 10.2
export LD_LIBRARY_PATH=/usr/local/cuda-10.0/lib64:$LD_LIBRARY_PATH # or cuda-10.2 if using CUDA 10.2
```

```
vi ./etc/conda/deactivate.d/env_vars.sh
### Seasoned developers

#!/bin/bash
unset PATH
unset LD_LIBRARY_PATH
```
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](https://github.com/rapidsai/cugraph/projects).

## Creating documentation
> **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

Python API documentation can be generated from [docs](docs) directory.
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.

## C++ ABI issues

cuGraph builds with C++14 features. By default, we build cuGraph with the latest ABI (the ABI changed with C++11). The version of cuDF pointed to in
the conda installation above is build with the new ABI.

If you see link errors indicating trouble finding functions that use C++ strings when trying to build cuGraph you may have an ABI incompatibility.

There are a couple of complications that may make this a problem:
* if you need to link in a library built with the old ABI, you may need to build the entire tool chain from source using the old ABI.
* if you build cudf from source (for whatever reason), the default behavior for cudf (at least through version 0.5.x) is to build using the old ABI. You can build with the new ABI, but you need to follow the instructions in CUDF to explicitly turn that on.

If you must build cugraph with the old ABI, you can use the following command (instead of the cmake call above):

```bash
cmake .. -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DCMAKE_CXX11_ABI=OFF
```

## Attribution
Portions adopted from https://github.com/pytorch/pytorch/blob/master/CONTRIBUTING.md
9 changes: 9 additions & 0 deletions PRTAGS.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Pull Request Tags
If you look at the list of current [Pull Request](https://github.com/rapidsai/cugraph/pulls) you will notice a set of bracketed tags in the subject line. Those tags help developers focus attention and know what is being asked.

PR = Pull Request

| TAG | |
|---------|-------------------------------------------------------|
| WIP | _Work In Progress_ - Within the RAPIDS cuGraph team, we try to open a PR when development starts. This allows other to review code as it is being developed and provide feedback before too much code needs to be refactored. It also allows process to be tracked |
| skip-ci | _Do Not Run CI_ - This flag prevents CI from being run. It is good practice to include this with the **WIP** tag since code is typically not at a point where it will pass CI.
3 changes: 2 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,8 @@ Note: This conda installation only applies to Linux and Python versions 3.6/3.7.
<a name="source"></a>
### Build from Source and Contributing

Please see our [guide for building and contributing to cuGraph](CONTRIBUTING.md).
Please see our [guide for building cuGraph from source](SOURCEBUILD.md).
Please see our [guide for contributing to cuGraph](CONTRIBUTING.md).



Expand Down

0 comments on commit dc5d397

Please sign in to comment.