Developers Guide

Contributions are welcome and can come in different forms, including but not limited to:

Environment Setup

In order to contribute to the project, it is a better idea to have your own local copy of CausalGPS on your Github account. Here are the steps:

Navigate to CausalGPS Github repository, and at the top right corner, click on the Fork button. This will add a clone of the project to your Github account.
Open your terminal (or Gitbash for Windows, Anaconda prompt, …) and run the following command (brackets are not included):

git clone git@github.com:[your user name]/CausalGPS.git

If you do not already have an SSH key, you need to generate one. Read more here.
Now, you can modify the codebase and track your modification.
It is a good idea to create a new branch to work on the codebase. Read the following instructions for git branching.

Git Branching Model

Although, in your personal repository, you can pick any branch name, however, in order to keep consistency and also understand who is working on what, the following convention is strongly recommended. In this project, we follow the convention that is proposed by Vincent Driessen in his A successful Git branching model post.

Here is the summary of the branches:

master: master branch only hosts the released software packages. Only project maintainers have write access on the master branch.
develop: develop branch is considered the main branch where the source code of HEAD always reflects a state with the latest delivered development changes for the next release.
supporting branch: There are different supporting branches, three main supporting branches that we suggest the contributors to follow the naming convention includes:
- feature: we start a new feature branch to add new features to the software. The naming convention is iss[issue_number]_short_description. For example, if I need to add unittest to one of the functions in the package and the issue number is 12, iss12_add_unittest can be a valid git branch name. We start it with the issue number to go back and take a look at the issue details if necessary. Although feature branches are temporary, this naming convention helps developers to understand the situation while working on the codebase. If you are working on some features that there is no open issue for that, please open an issue here and assign it to yourself. You can also make a comment that you are working on that.
- hotfix: hotfix branches will be only used for fixing a bug on a released package. After fixing the bug, the third digit of the version number should be incremented by one. For example, 2.3.5 –> 2.3.6. These branches will be prefixed with hotfix and followed by the upcoming version number (e.g., in this case, hotfix_2.3.6)
- release: Release branches support the preparation of a new production release.

Where to submit pull requests?

All pull requests should be submitted to base repository: NSAPH-Software/CausalGPS and base: develop branch.

Pull request checklist

Please run devtools::document(), devtools::load_all() after your final modifications.
Make sure that your modified code passes all checks and tests (you can run devtools::check() in RStudio)
Your PR should pass all the CI and reviews so we can merge it.
Add a line(s) about the modification to the NEWS.md file.
If you are adding new features, please make sure that appropriate documentation is added or updated.
Please clean up white spaces. Read more here.

Reporting bugs

Please report potential bugs by creating a new issue or sending us an email. Please include the following information in your bug report:

A brief description of what you are doing, what you expected to happen, and what happened.
OS that you are using and whether you are using a personal computer or HPC cluster.
The version of the package that you have installed.

Style Guide

In this project, we follow the tidyverse style guide.

Summary

Names

File names all snake_case and ends with .R (e.g., create_matching.R)
variable names small letter and separate with _ if need (e.g., delta_n)
Function names should follow snake_case style (e.g., generate_data)
Function names follow verb+output convention (e.g., compute_resid)

Spaces and Indentation

Indentations are two spaces (do not use tab)
Place space around binary operators (e.g., x + y)

#Acceptable:
z <- x + y

#Not recommended:
z<-x+y # (no space)
z<- x+y
z<-x +y

Place space after comma

#Acceptable:
a <- matrix(c(1:100), nrow = 5)

#Not recommended:
a <- matrix(c(1:100),nrow = 5) # (no space after comma)
a <- matrix( c(1:100), nrow = 5 ) # (extra space after and before parentheses)
a<-matrix(c(1:100), nrow = 5) # (no space around unary operator <- )

Place space after # and before commenting and avoid multiple ###

#Acceptable:
# This is a comment

#Not recommended:
#This is a comment
#    This is a comment (more than one space after #)
## This is a comment (multiple #)
###    This is a comment (multiple # and more than one space)

Do not put space at the opening and closing the parenthesis

#Acceptable:
x <- (z + y)

#Not recommended:
x <- ( z + y ) # (unnecessary space)
x <- (z + y )
x <- ( z + y)

Place a space before and after () when used with if, for, or while.


#Acceptible
if (x > 2) {
  print(x)
}

# Not recommended
if(x > 2){
  print(x)
}

Other notes

Maximum line length is 80 character
Use explicit returns
Use explicit tags in documentation (e.g., @title, @description, …)