# Contributing

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 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. Please use Conventional Commits 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

## Microbenchmarks

We use 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