|
| 1 | +# DoubleML - Contributing Guidelines <a href="https://docs.doubleml.org"><img src="man/figures/logo.png" align="right" width = "120" /></a> |
| 2 | + |
| 3 | +DoubleML is a community effort. |
| 4 | +Everyone is welcome to contribute. |
| 5 | +All contributors should adhere to this contributing guidelines |
| 6 | +and our [code of conduct](https://github.com/DoubleML/doubleml-for-r/blob/master/CODE_OF_CONDUCT.md). |
| 7 | +The contributing guidelines are particularly helpful to get started for your first contribution. |
| 8 | + |
| 9 | +## Submit a Bug Report :bug: |
| 10 | +To submit a **bug report**, you can use our |
| 11 | +[issue template for bug reports](https://github.com/DoubleML/doubleml-for-r/issues/new/choose). |
| 12 | + |
| 13 | +- A good bug report contains a **minimum reproducible code snippet**, like for example |
| 14 | + |
| 15 | +```R |
| 16 | +library(DoubleML) |
| 17 | +library(mlr3) |
| 18 | +library(mlr3learners) |
| 19 | +library(data.table) |
| 20 | +set.seed(2) |
| 21 | +ml_g = lrn("regr.ranger", num.trees = 10, max.depth = 2) |
| 22 | +ml_m = ml_g$clone() |
| 23 | +obj_dml_data = make_plr_CCDDHNR2018(alpha = 0.5) |
| 24 | +dml_plr_obj = DoubleMLPLR$new(obj_dml_data, ml_g, ml_m) |
| 25 | +dml_plr_obj$fit() |
| 26 | +dml_plr_obj$summary() |
| 27 | +``` |
| 28 | + |
| 29 | +- State the **result you would have expected** and the **result you actually got**. |
| 30 | +In case of an exception the full traceback is appreciated. |
| 31 | + |
| 32 | +- State the **versions of your code** by running the following lines and copy-paste the result. |
| 33 | + |
| 34 | +```R |
| 35 | +sessionInfo() |
| 36 | +packageVersion('DoubleML') |
| 37 | +packageVersion('mlr3') |
| 38 | +``` |
| 39 | + |
| 40 | +## Submit a Feature Request :bulb: |
| 41 | +We welcome **feature requests and suggestions** towards improving and/or extending the DoubleML package. |
| 42 | +For feature requests you can use the corresponding |
| 43 | +[issue template](https://github.com/DoubleML/doubleml-for-r/issues/new/choose). |
| 44 | + |
| 45 | +## Submit a Question or Start a Discussion |
| 46 | +We use **[GitHub Discussions](https://github.com/DoubleML/doubleml-for-r/discussions)** to give the community a platform |
| 47 | +for asking questions about the DoubleML package and for discussions on topics related to the package. |
| 48 | + |
| 49 | +## Contribute Code :computer: |
| 50 | +Everyone is welcome to contribute to the DoubleML code base. |
| 51 | +The following guidelines and hints help you to get started. |
| 52 | + |
| 53 | +### Development Workflow |
| 54 | +In the following, the recommended way to contribute to DoubleML is described in detail. |
| 55 | +If you are just starting to work with Git and GitHub, we recommend to read [Happy Git and GitHub for the useR](https://happygitwithr.com/index.html) and the [chapter on Git and GitHub](https://r-pkgs.org/git.html) in Hadley Wickham's book R Packages. |
| 56 | +The most important steps are: To **fork** the repo, then **add your changes** and finally submit a **pull-request**. |
| 57 | +1. **Fork** the [DoubleML repo](https://github.com/DoubleML/doubleml-for-r) |
| 58 | +by clicking on the Fork button (this requires a GitHub account). |
| 59 | + |
| 60 | +2. **Clone** your fork to your local machine via |
| 61 | +```bash |
| 62 | +$ git clone git@github.com:YourGitHubAccount/doubleml-for-r.git |
| 63 | +$ cd doubleml-for-r |
| 64 | +``` |
| 65 | + |
| 66 | +3. Create a **feature branch** via |
| 67 | +```bash |
| 68 | +$ git checkout -b my_feature_branch |
| 69 | +``` |
| 70 | + |
| 71 | +4. (Optionally) you can add the `upstream` remote. |
| 72 | +```bash |
| 73 | +$ git remote add upstream https://github.com/DoubleML/doubleml-for-r.git |
| 74 | +``` |
| 75 | +This allows you to easily keep your repository in synch via |
| 76 | +```bash |
| 77 | +$ git fetch upstream |
| 78 | +$ git merge upstream/master |
| 79 | +``` |
| 80 | + |
| 81 | +5. **Develop** your code changes. A helpful resource for package development in R |
| 82 | +is Hadley Wickham's [R Packages](https://r-pkgs.org/preface.html) and [rOpenSci Packages](https://devguide.ropensci.org/). |
| 83 | +The changes can be added and pushed via |
| 84 | +```bash |
| 85 | +$ git add your_new_file your_modified_file |
| 86 | +$ git commit -m "A commit message which briefly summarizes the changes made" |
| 87 | +$ git push origin my_feature_branch |
| 88 | +``` |
| 89 | + |
| 90 | +6. Generate a **pull request** from your fork. |
| 91 | +Please follow our guidelines for pull requests. |
| 92 | +When opening the PR you will be guided with a checklist. |
| 93 | + |
| 94 | +### Checklist for Pull Requests (PR) |
| 95 | +- [x] The **title** of the pull request summarizes the changes made. |
| 96 | + |
| 97 | +- [x] The PR contains a **detailed description** of all changes and additions |
| 98 | +(you may want to comment on the diff in GitHub). |
| 99 | + |
| 100 | +- [x] **References** to related issues or PRs are added. |
| 101 | + |
| 102 | +- [x] The code passes `R CMD check` and **all (unit) tests**. |
| 103 | +To check your code for common problems, run |
| 104 | +```R |
| 105 | +devtools::check() |
| 106 | +``` |
| 107 | +By default, this runs all tests. In case you only want to run the tests, run |
| 108 | +```R |
| 109 | +devtools::test() |
| 110 | +``` |
| 111 | + |
| 112 | +- [x] If you add an **enhancements** or **new feature**, **unit tests** |
| 113 | +(with a certain level of coverage) are **mandatory** for getting the PR merged. |
| 114 | + |
| 115 | +- [x] Check whether your changes adhere to the **"mlr-style" standards**. |
| 116 | +For the check you can use the following code |
| 117 | +```R |
| 118 | +require(styler) |
| 119 | +remotes::install_github("pat-s/styler@mlr-style") |
| 120 | +styler::style_pkg(style = styler::mlr_style) # entire package |
| 121 | +styler::style_file(<file>, style = styler::mlr_style) # specific file |
| 122 | +``` |
| 123 | + |
| 124 | +If your PR is still **work in progress**, please consider marking it a **draft PR** |
| 125 | +(see also [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)). |
| 126 | + |
| 127 | +### Unit Tests and Test Coverage |
| 128 | +We use the **testthat** package for unit testing. |
| 129 | +Unit testing is considered to be a fundamental part of the development workflow. |
| 130 | +We recommend to read the [chapter on testing](https://r-pkgs.org/tests.html) of Hadley Wickham's book R Packages. |
| 131 | +The tests are located in the `tests/testthat` subfolder. |
| 132 | +The test coverage is determined with the `covr` package. |
| 133 | +Coverage reports for the package, PRs, branches etc. are available from |
| 134 | +[codecov](https://app.codecov.io/gh/DoubleML/doubleml-for-r). |
| 135 | +It is mandatory to equip new features with an appropriate level of unit test coverage. |
| 136 | +To **run all unit tests** (for further option see the [devtools docu](https://devtools.r-lib.org/reference/test.html)) call |
| 137 | +```R |
| 138 | +devtools::test() |
| 139 | +``` |
| 140 | +For a unit test coverage report you can run |
| 141 | +```R |
| 142 | +covr::report() |
| 143 | +``` |
| 144 | +or, alternatively, |
| 145 | +```R |
| 146 | +devtools::test_coverage() |
| 147 | +``` |
| 148 | + |
| 149 | +### Contribute a New Model Class |
| 150 | +The **DoubleML package** is particularly designed in a flexible way to make it **easily extendable** with regard to |
| 151 | +**new model classes**. |
| 152 | +**Contributions** in this direction **are very much welcome**, and we are happy to help authors to integrate their models in the |
| 153 | +DoubleML OOP structure. |
| 154 | +If you need assistance, just open an issue or contact one of the maintainers |
| 155 | +[@MalteKurz](https://github.com/MalteKurz) or [@PhilippBach](https://github.com/PhilippBach). |
| 156 | + |
| 157 | +The **abstract base class `DoubleML` implements all core functionalities** based on a linear Neyman orthogonal score |
| 158 | +function. |
| 159 | +To contribute a new model class, you only need to **specify all nuisance functions** that need to be estimated for the |
| 160 | +new model class (e.g. regressions or classifications). |
| 161 | +Furthermore, the **score components for the Neyman orthogonal score function need to be implemented**. |
| 162 | +All other functionality is automatically available via inheritance from the abstract base class. |
| 163 | +<!---TODO: Add a model template for the R package DoubleML |
| 164 | +A **template for new model classes** is available |
| 165 | +[here](https://github.com/DoubleML/doubleml-docs/blob/master/model_templates/double_ml_model_template.py).---> |
| 166 | + |
| 167 | +## Contribute Documentation :books: |
| 168 | + |
| 169 | +The **documentation** of DoubleML is generated with **roxygen2**. The corresponding website |
| 170 | +for the R API documentation is generated using **pkgdown** and hosted at |
| 171 | +[https://docs.doubleml.org/r/stable](https://docs.doubleml.org/r/stable/). |
| 172 | +The website [https:://docs.doubleml.org](https://docs.doubleml.org) is built with |
| 173 | +sphinx. |
| 174 | +The source code for the website, user guide, example gallery, etc. is available in a separate repository |
| 175 | +[https://github.com/DoubleML/doubleml-docs](https://github.com/DoubleML/doubleml-docs). |
| 176 | + |
| 177 | +### Contribute to the API Documentation |
| 178 | +The **documentation** of DoubleML is generated with **roxygen2**. The corresponding website |
| 179 | +for the R API documentation is generated using **pkgdown**. |
| 180 | +To build the documentation of the package run |
| 181 | +```R |
| 182 | +devtools::document() |
| 183 | +``` |
| 184 | +To build the documentation website, run (for more details, see the [pkgdown documentation](https://pkgdown.r-lib.org/)) |
| 185 | +```R |
| 186 | +pkgdown::build_site() |
| 187 | +``` |
| 188 | + |
| 189 | +### Contribute to the User Guide and Documentation |
| 190 | +The **documentation of DoubleML** is hosted at [https://docs.doubleml.org](https://docs.doubleml.org). |
| 191 | +The **source code** for the website, user guide, example gallery, etc. is available in a **separate repository |
| 192 | +[doubleml-docs](https://github.com/DoubleML/doubleml-docs)**. |
| 193 | +Changes, issues and PRs for the documentation (except the API documentation) should be discussed in the |
| 194 | +[doubleml-docs](https://github.com/DoubleML/doubleml-docs) repo. |
| 195 | +We welcome contributions to the user guide, especially case studies for the |
| 196 | +[example gallery](https://docs.doubleml.org/stable/examples/index.html). |
| 197 | +A step-by-step guide for contributions to the example gallery is available |
| 198 | +[here](https://github.com/DoubleML/doubleml-docs/wiki/Contribute-to-our-Website-and-Example-Gallery). |
0 commit comments