---
title: "Contributing"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Contributing}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

Thank you for taking the time to contribute to Individual. We're grateful that you would take some time to make Individual-Based Modeling easier in R. Pull requests are very welcome.

## Issues

For major changes, please open an issue first to give other developers a heads up on what you would like to add or change. That way we can reduce any redundant efforts and give any resources if needed.

For bug reports please include:

 * R version
 * OS
 * Steps to recreate
 * Expected behaviour
 * Actual behaviour

## Git

We use Git on this project. Which means we use `master`, `dev`, `feat/*`, `bug/*`, `hotfix/*` and `release/*` branches. Please refer to [this post](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) for more information of each type of branch. NOTE: `bug/*` branches are `feat/*` branches which fix a bug.

Practically speaking, *all* new code contributions should be feature branches. You should branch off of the `dev` branch into one called `feat/[your feature name here]`. When we consider pull requests from forked repositories to the mrc-ide/individual repository, we will expect this convention.

We periodically merge `dev` into `master` for small release updates. These releases will appear on the [GitHub releases page](https://github.com/mrc-ide/individual/releases). Please use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as it helps us version Individual properly. 

Large releases will have a `release/*` branch to manage the transition. No new features will be merged into `release/*` branches. Only documentation and bug fixes will be considered.

## Code organisation

*R/simulation.R* - Contains the main entry point and configuration for models

*R/variables.R* - Defines classes for the available variables

*R/events.R* - Defines classes for the available events

*src/* - The C++ side of the R interface and tests

*inst/include/Variable.h* - The implementations of Variables

*inst/include/Event.h* - The implementations of Events

*tests/* - are divided into unit, integration and performance tests. Integration tests are
strongly recommended for large functions and unit tests for everything else

## Pull Requests

Here's a checklist for a successful PR:

 - Read your own diff
 - Describe your PR
 - Write any particular notes of interest for the reviewer
 - Check that your code passes all CI checks
 - Check that your code is mergeable
 
 These are the things we check for:
 
 - Do I understand the code?
 - Does the code look like it would work?
 - Does it work when run locally?
 - Is it tested enough?
 - Is it documented enough?

Our review process is based off of [RESIDE's PR review process](https://reside-ic.github.io/articles/pull-requests/)

## Microbenchmarks

We have R based benchmarks in tests/performance. Please add new benchmarks for performance critical code.

Please note the google benchmarks are deprecated. The below instructions will not work since building requires including R and Rcpp.

We use [google benchmark](https://github.com/google/benchmark) for our
microbenchmarks. You can compile and run the benchmarks like this:

```
cd tests/performance
g++ *_benchmark.cpp -std=c++14 -lbenchmark -lpthread -o benchmark.out
./benchmark.out
```

## Wishlist

 * 90% test coverage
 * More Variables
 * Speed optimisations (tests TBC)
 * CRAN
 * Anything on the github issue board