How to contribute

Source: vignettes/how-to-contribute.Rmd

Two ways to collaborate

There are two ways to collaborate with IVI.

  1. You can comment on the scientific approach or evidence considered. IVI and a technical panel will review the comments and determine whether they should be incorporated into the model. Information on how to do this is available here. A synthesis of the feedback we have received can be found here.

  2. You can make changes to the code itself by making a pull request. Code changes that affect the scientific approach or evidence considered will only be incorporated after a review by the technical panel but other changes such as bug fixes or performance improvements may be immediately accepted.

IVI model releases

New releases of the IVI-RA model follow the paradigm described by Hadley Wickham. Package versions follow the format major.minor.patch.

  • Patch: A patch is a bug fix without any significant new features (e.g., 1.0.1).

  • Minor release: A minor release includes bug fixes or significant new features like a speed improvement (e.g., 1.1.0).

  • Major release: A major release involves a change to the scientific approach or evidence considered (e.g, 2.0.0).

Patches and minor releases do not need to be reviewed by the technical expert panel and can be implemented through pull requests. Major releases only occur after improvements have been recommended by the panel.

Style guide

We, for the most part, adhere to Hadley Wickham’s style guide, with a few exceptions and clarifications.

Variable names

Variable names should be all lower case and separated by a dot.

# Good
object.name
my.list <- list(my.integer = 3)

# Bad 
objectName
ObjectName
object_name

Function names

Function names should be all lower case and separated by an underscore.

# Good
my_function

# Bad 
myFunction
MyFunction
my.function

Variable and column names in data frames or matrices

Variable names in a data.frame, data.table, or matrix should be all lower case and separated by an underscore.

# Good
data.frame(my_var = 3)

# Bad 
data.frame(myVar = 3)
data.frame(MyVar = 3)
data.frame(my.var = 3)

Pull requests

To collaborate on the source code, you will need to create a GitHub account and install Git on your machine. Once your setup you can then follow the steps outlined below to contribute to the model.

Step 1: After signing into GitHub, you need to create your own remote repository of the IVI model. Click the “Fork” button in the upper right corner of the IVI-RA Github page. When asked “Where should we fork this repository?” select your username.

Step 2: Use the command line to create a directory where you would like your local repository to live, and navigate to this directory.

Step 3: Create a local repository by typing the following command into the command line:

git clone https://github.com/[github-username]/IVI-RA.git

Step 4: Use the command line to navigate to the local IVI-RA directory.

Step 5: In order to make it easier to Push your local work and pull changes made by others to the IVI-RA code type the following command into the command line:

git remote add upstream https://github.com/InnovationValueInitiative/IVI-RA.git

Step 6: Before editing your local copy of the IVI-RA code, make sure you have the latest version of the code using the following three commands:

  • Step 6a: Download all content from the central IVI-RA repository. Navigate to your local IVI-RA repository and type the following command into the command line:

    git fetch upstream

  • Step 6b: Switch to the master branch in your local IVI-RA repository by typing the following command into the command line:

    git checkout master

  • Step 6c: Update your local master IVI-RA branch to the latest version of the central IVI-RA master branch by using the merge command:

    git merge upstream/master

Step 7: Create a new branch on your local machine. Branches are a way to organize your project. To create a new branch type the following command into the command line:

git checkout -b [new-branch-name]

Step 8: After making changes to your local IVI-RA repository, commit your changes to the central IVI-RA repository. To add a new file type the following command into the command file:

git add [filename]

To commit the added file or an edited file type the following command into the command line:

git commit -m "[description-of-the-changes-you-made]"

To find all files that were edited or new files that were created, but not yet committed, type the following command into the command line:

git status

Step 9: Periodically check whether the branch created in Step 7 is in sync with changes made by other contributors by fetching upstream and merging upstream master into your branch:

git fetch upstream
git merge upstream/master

If the changes you made to your local branch are in the same section as changes made by other contributors, you may need to resolve conflicts.

Step 10: If the code is ready to be reviewed by other contributors, make a final commit and push your local branch to your remote repository:

git push origin [new-branch-name]

Step 11: Using the GitHub user interface, open a pull request.