Developers Guide
Contributions are appreciated and can take various forms, such
as:
- Adding new features.
- Enhancing documentation.
- Addressing existing open issues.
- Creating new issues.
- Correcting typos.
Please review the following documents before making changes to the
codebase.
Environment Setup
To contribute to the project, it’s recommended to have your own local
copy of GPCERF on your Github account. As a result, please fork
the project. Then 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]/GPCERF.git
- If you haven’t already, generate an SSH key. Learn more here.
Now, you can modify the codebase and track your changes. Consider
creating a new branch to work on the codebase. Refer to the following
instructions for git branching.
Git Branching Model
While you can choose any branch name for your personal repository,
maintaining consistency and understanding who’s working on what is
crucial. 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:
- main: The main branch only hosts released software
packages. Only project maintainers have write access to the master
branch.
- develop: The develop branch serves as the primary
branch, with the source code of HEAD always reflecting the latest
delivered development changes for the next release.
- supporting branch: There are various supporting
branches. We recommend contributors follow the naming convention for
three main supporting branches:
- 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?
Submit all pull requests to
base repository: NSAPH-Software/GPCERF
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 for merging.
- 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
#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, …)
Notes on SuperLearner
In this package we create a customized wrapper for the SuperLearner
internal libraries. Please read Notes on SL Wrappers for more
details.
Logger
Use the logger to examine the internal process. By default, the level
is set to “INFO”, writing messages to the “GPCERF.log” file. To change
the log file location and level, use the update_logger function.