Contributing

Source: vignettes/Contributing.Rmd

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