Contributor Guide

  • Thank you for participating!

  • Below are the guids about how to contribute to it.

The repository consists of different branches:
  • the master branch includes the main stable developments for the next major version.

  • the dev branch includes latest developments. A contribution should be based on the dev branch.

  • the <version> branch includes deployments for different versions.

Generally all pull requests are to be created against the iDDS dev branch. Contributions will end up in the upstream dev when merged.

Getting started

Step 1: Fork the repository on Github.

Step 2: Clone the repository to your development machine and configure it:

$ git clone<YOUR_USER>/iDDS/
$ cd iDDS
$ git remote add upstream

Step 3: Setup local dev environment(The virtual environment is based on conda):

$ # If you are not in the idds top directory.
$ # cd iDDS
$ CurrentDir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
$ CondaDir=${CurrentDir}/.conda/iDDS
$ mkdir -p $CondaDir

$ # For your local development, you may do not need all packages. In this case, you may need to comment out some packages, for example cx_Oracle.
$ echo conda env create --prefix=$CondaDir  -f=main/tools/env/environment.yml
$ conda env create --prefix=$CondaDir  -f=main/tools/env/environment.yml

Step 4: Configure local environment:

$ # If you are not in the idds top directory.
$ # cd iDDS
$ RootDir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
$ CondaDir=${RootDir}/.conda/iDDS
$ export IDDS_HOME=$RootDir
$ conda activate $CondaDir


Step 1: Developing based on your personal repository(if you already have some codes and want to keep them, you need to use ‘git rebase’. In this case, you may need to fix some conflicts; If you start from scratch, you can directly use ‘git reset’. This method will overwrite local changes. Becareful to backup if you are not confident about using it):

$ git checkout dev
$ # echo "Updating dev"
$ git pull --all --prune --progress
$ echo "Rebasing dev"
$ # git rebase upstream/dev dev
$ git reset --hard upstream/dev

Step 2: Check your codes and fix the codes(flake8 is installed when you configure your virtual environments):

$ flake8
$ flake8 */lib/idds/

Step 3: Commit your change. The commit command must include a specific message format:

$ git commit -m "...."
$ git push origin dev

Step 4: Create the pull request to the dev branch of HSF/iDDS repository.

While using the github interface is the default interface to create pull requests, you could also use GitHub’s command-line wrapper hub or the GitHub CLI.

Step 5: Watch the pull request for comments and reviews. If there are some conflicts, you may need to rebase your codes and fix the conflicts. For any pull requests update, please try to squash/amend your commits to avoid “in-between” commits:

$ git rebase upstream/dev dev

Human Review

Anyone is welcome to review merge requests and make comments!

The development team can approve, request changes, or close pull requests. Merging of approved pull requests is done by the iDDS development lead.

Coding Style

We use flake8 to sanitize our code. Please do the same before submitting a pull request.