Skip to content

How to Contribute

Before you get started

Commit an issue on the github or forum

You are welcome to contribute any code or files to the project. But firstly we suggest you raise an issue on the github or the forum to start a discussion with the community. Check through the topic for Github.

Sign the Contributor License Agreement (CLA)

What is CLA?

Here is the vesoft inc. Contributor License Agreement.

Click the Sign in with GitHub to agree button to sign the CLA.

If you have any questions, send an email to info@vesoft.com.

Modify a single document

This manual is written in the Markdown language. Click the pencil icon on the right of the document title to commit the modification.

This method applies to modify a single document only.

Batch modify or add files

This method applies to contribute codes, modify multiple documents in batches, or add new documents.

Step 1: Fork in the github.com

The NebulaGraph project has many repositories. Take the nebul repository for example:

  1. Visit https://github.com/vesoft-inc/nebula.

  2. Click the Fork button to establish an online fork.

Step 2: Clone Fork to Local Storage

  1. Define a local working directory.

    # Define the working directory.
    working_dir=$HOME/Workspace
    
  2. Set user to match the Github profile name.

    user={the Github profile name}
    
  3. Create your clone.

    mkdir -p $working_dir
    cd $working_dir
    git clone https://github.com/$user/nebula.git
    # or: git clone git@github.com:$user/nebula.git
    
    cd $working_dir/nebula
    git remote add upstream https://github.com/vesoft-inc/nebula.git
    # or: git remote add upstream git@github.com:vesoft-inc/nebula.git
    
    # Never push to upstream master since you do not have write access.
    git remote set-url --push upstream no_push
    
    # Confirm that the remote branch is valid.
    # The correct format is:
    # origin    git@github.com:$(user)/nebula.git (fetch)
    # origin    git@github.com:$(user)/nebula.git (push)
    # upstream  https://github.com/vesoft-inc/nebula (fetch)
    # upstream  no_push (push)
    git remote -v
    
  4. (Optional) Define a pre-commit hook.

    Please link the NebulaGraph pre-commit hook into the .git directory.

    This hook checks the commits for formatting, building, doc generation, etc.

    cd $working_dir/nebula/.git/hooks
    ln -s $working_dir/nebula/.linters/cpp/hooks/pre-commit.sh .
    

    Sometimes, the pre-commit hook cannot be executed. You have to execute it manually.

    cd $working_dir/nebula/.git/hooks
    chmod +x pre-commit
    

Step 3: Branch

  1. Get your local master up to date.

    cd $working_dir/nebula
    git fetch upstream
    git checkout master
    git rebase upstream/master
    
  2. Checkout a new branch from master.

    git checkout -b myfeature
    

    Note

    Because the PR often consists of several commits, which might be squashed while being merged into upstream. We strongly suggest you to open a separate topic branch to make your changes on. After merged, this topic branch can be just abandoned, thus you could synchronize your master branch with upstream easily with a rebase like above. Otherwise, if you commit your changes directly into master, you need to use a hard reset on the master branch. For example:

    git fetch upstream
    git checkout master
    git reset --hard upstream/master
    git push --force origin master
    

Step 4: Develop

  • Code style

    NebulaGraph adopts cpplint to make sure that the project conforms to Google's coding style guides. The checker will be implemented before the code is committed.

  • Unit tests requirements

    Please add unit tests for the new features or bug fixes.

  • Run tests

    In the root directory of nebula, run the following command:

    cd nebula/build
    ctest -j$(nproc)
    

Step 5: Bring Your Branch Update to Date

# While on your myfeature branch.
git fetch upstream
git rebase upstream/master

Users need to bring the head branch up to date after other contributors merge PR to the base branch.

Step 6: Commit

Commit your changes.

git commit -a

Users can use the command --amend to re-edit the previous code.

Step 7: Push

When ready to review or just to establish an offsite backup, push your branch to your fork on github.com:

git push origin myfeature

Step 8: Create a Pull Request

  1. Visit your fork at https://github.com/$user/nebula (replace $user here).

  2. Click the Compare & pull request button next to your myfeature branch.

Step 9: Get a Code Review

Once your pull request has been created, it will be assigned to at least two reviewers. Those reviewers will do a thorough code review to make sure that the changes meet the repository's contributing guidelines and other quality standards.

Add test cases

For detailed methods, see How to add test cases.

Donation

Step 1: Confirm the project donation

Contact the official NebulaGraph staff via email, WeChat, Slack, etc. to confirm the donation project. The project will be donated to the NebulaGraph Contrib organization.

Email address: info@vesoft.com

WeChat: NebulaGraphbot

Slack: Join Slack

Step 2: Get the information of the project recipient

The NebulaGraph official staff will give the recipient ID of the NebulaGraph Contrib project.

Step 3: Donate a project

The user transfers the project to the recipient of this donation, and the recipient transfers the project to the NebulaGraph Contrib organization. After the donation, the user will continue to lead the development of community projects as a Maintainer.

For operations of transferring a repository on GitHub, see Transferring a repository owned by your user account.


Last update: February 1, 2023