---
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 **Micro-MoB** (Microsimulation for Mosquito-Borne pathogens).

## Issues

If you find a bug, have a question about how to use a feature that does not have sufficient documentation, or have a suggestion for improvement, please leave an issue at our GitHub repo.

For bug reports please include:

 * **Micro-MoB** version
 * Operating System
 * R version
 * Steps to recreate
 * Expected behaviour
 * Actual behaviour

## Git

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

  * `main`: this branch always stores the last "production" release of the software, and is a protected branch. A pull request should
  not be submitted to `main` unless it is from `dev`, meaning that the software version should be updated.
  * `dev`: all pull requests from users should be made to the `dev` branch. This branch is protected from deletion.
  * `feat`: new and significantly enhanced features are made in `feat` branches before being merged with `dev`. After a `feat/*` branch is merged
  with `dev`, it can be deleted.
  * `bug`: these branches fix bugs, usually after being raised as an issue. After a `bug/*` branch is merged with `dev`, it can be deleted.
  * `hotfix`: the difference between a `bug/*` and `hotfix/*` branch is `hotfix` is for small quick fixes (misspellings, incorrect arguments, etc.)
  and are short-lived. After being merged with `dev`, they can be deleted.

We periodically merge `dev` into `main` for small release updates. These releases will appear on the [GitHub releases page](https://github.com/dd-harp/MicroMoB/releases). 

## Continuous integration

We use GitHub Actions as our continuous integration platform to run workflows.
The workflows we use are from [r-lib/actions](https://github.com/r-lib/actions)
for R packages.

We run three types of workflows.

[R CMD check](https://github.com/r-lib/actions/blob/master/examples/check-standard.yaml)
runs during any pull request to `[main, dev]` branches.

[Test coverage](https://github.com/r-lib/actions/blob/master/examples/test-coverage.yaml)
runs during pull requests to `[main, dev]` and uses our [codecov.io integration](https://app.codecov.io/gh/dd-harp/MicroMoB)
for checking test coverage.

Finally, [pkgdown](https://github.com/r-lib/actions/blob/master/examples/pkgdown.yaml)
only runs on pushes to `main`, which will occur when `dev` is merged with `main`
periodically.

Please note that sometimes hard to diagnose bugs can be due to out of date
workflows. If you find a strange or unusual bug coming from a workflow, this
is something to consider checking.

## Pull Requests

If making a pull request, please only use `dev` as the base branch. If you are adding a new feature (i.e. the pull is from a `feat/*` branch),
please ensure you have added minimal tests using testthat so that the functionality of your feature can be tested.