-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathCONTRIBUTING.html
212 lines (164 loc) · 10.2 KB
/
CONTRIBUTING.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
<!-- Generated by pkgdown: do not edit by hand -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Contributing to biotmle development • biotmle</title>
<!-- jquery -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<!-- Bootstrap -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.4.0/readable/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script>
<!-- bootstrap-toc -->
<link rel="stylesheet" href="bootstrap-toc.css">
<script src="bootstrap-toc.js"></script>
<!-- Font Awesome icons -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous" />
<!-- clipboard.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script>
<!-- headroom.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script>
<!-- pkgdown -->
<link href="pkgdown.css" rel="stylesheet">
<script src="pkgdown.js"></script>
<meta property="og:title" content="Contributing to biotmle development" />
<!-- mathjax -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script>
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body data-spy="scroll" data-target="#toc">
<div class="container template-title-body">
<header>
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span class="navbar-brand">
<a class="navbar-link" href="index.html">biotmle</a>
<span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">1.17.0</span>
</span>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li>
<a href="index.html">
<span class="fas fa-home fa-lg"></span>
</a>
</li>
<li>
<a href="reference/index.html">Reference</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
Articles
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="articles/exposureBiomarkers.html">Identifying Biomarkers from an Exposure Variable with `biotmle`</a>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li>
<a href="https://github.com/nhejazi/biotmle/">
<span class="fab fa-github fa-lg"></span>
</a>
</li>
</ul>
</div><!--/.nav-collapse -->
</div><!--/.container -->
</div><!--/.navbar -->
</header>
<div class="row">
<div class="contents col-md-9">
<div class="page-header">
<h1>Contributing to biotmle development</h1>
</div>
<div id="contributing-to-biotmle-development" class="section level1">
<p>We, the authors of the <code>biotmle</code> R package, use the same guide as is used for contributing to the development of the popular <code>tidyverse</code> ecosystem of R packages. This document is simply a formal re-statement of that fact.</p>
<p>The goal of this guide is to help you get up and contributing to <code>biotmle</code> as quickly as possible. The guide is divided into two main pieces:</p>
<ul>
<li>Filing a bug report or feature request in an issue.</li>
<li>Suggesting a change via a pull request.</li>
</ul>
<div id="issues" class="section level2">
<h2 class="hasAnchor">
<a href="#issues" class="anchor"></a>Issues</h2>
<p>When filing an issue, the most important thing is to include a minimal reproducible example so that we can quickly verify the problem, and then figure out how to fix it. There are three things you need to include to make your example reproducible: required packages, data, code.</p>
<ol>
<li><p><strong>Packages</strong> should be loaded at the top of the script, so it’s easy to see which ones the example needs.</p></li>
<li><p>The easiest way to include <strong>data</strong> is to use <code><a href="https://rdrr.io/r/base/dput.html">dput()</a></code> to generate the R code to recreate it.</p></li>
<li>
<p>Spend a little bit of time ensuring that your <strong>code</strong> is easy for others to read:</p>
<ul>
<li><p>make sure you’ve used spaces and your variable names are concise, but informative</p></li>
<li><p>use comments to indicate where your problem lies</p></li>
<li><p>do your best to remove everything that is not related to the problem. The shorter your code is, the easier it is to understand.</p></li>
</ul>
</li>
</ol>
<p>You can check you have actually made a reproducible example by starting up a fresh R session and pasting your script in.</p>
<p>(Unless you’ve been specifically asked for it, please don’t include the output of <code><a href="https://rdrr.io/r/utils/sessionInfo.html">sessionInfo()</a></code>.)</p>
</div>
<div id="pull-requests" class="section level2">
<h2 class="hasAnchor">
<a href="#pull-requests" class="anchor"></a>Pull requests</h2>
<p>To contribute a change to <code>biotmle</code>, you follow these steps:</p>
<ol>
<li>Create a branch in git and make your changes.</li>
<li>Push branch to GitHub and issue pull request (PR).</li>
<li>Discuss the pull request.</li>
<li>Iterate until either we accept the PR or decide that it’s not a good fit for <code>biotmle</code>.</li>
</ol>
<p>Each of these steps are described in more detail below. This might feel overwhelming the first time you get set up, but it gets easier with practice.</p>
<p>If you’re not familiar with git or GitHub, please start by reading <a href="http://r-pkgs.had.co.nz/git.html" class="uri">http://r-pkgs.had.co.nz/git.html</a></p>
<p>Pull requests will be evaluated against a checklist:</p>
<ol>
<li>
<strong>Motivation</strong>. Your pull request should clearly and concisely motivates the need for change. Please describe the problem your PR addresses and show how your pull request solves it as concisely as possible.</li>
</ol>
<p>Also include this motivation in <code>NEWS</code> so that when a new release of <code>biotmle</code> comes out it’s easy for users to see what’s changed. Add your item at the top of the file and use markdown for formatting. The news item should end with <code>(@yourGithubUsername, #the_issue_number)</code>.</p>
<ol>
<li>
<p><strong>Only related changes</strong>. Before you submit your pull request, please check to make sure that you haven’t accidentally included any unrelated changes. These make it harder to see exactly what’s changed, and to evaluate any unexpected side effects.</p>
<p>Each PR corresponds to a git branch, so if you expect to submit multiple changes make sure to create multiple branches. If you have multiple changes that depend on each other, start with the first one and don’t submit any others until the first one has been processed.</p>
</li>
<li><p><strong>Use <code>biotmle</code> coding style</strong>. To do so, please follow the <a href="http://style.tidyverse.org">official <code>tidyverse</code> style guide</a>. Maintaining a consistent style across the whole code base makes it much easier to jump into the code. If you’re modifying existing <code>biotmle</code> code that doesn’t follow the style guide, a separate pull request to fix the style would be greatly appreciated.</p></li>
<li><p>If you’re adding new parameters or a new function, you’ll also need to document them with <a href="https://github.com/klutometis/roxygen"><code>roxygen2</code></a>. Make sure to re-run <code><a href="https://devtools.r-lib.org//reference/document.html">devtools::document()</a></code> on the code before submitting.</p></li>
</ol>
<p>This seems like a lot of work but don’t worry if your pull request isn’t perfect. It’s a learning process. A pull request is a process, and unless you’ve submitted a few in the past it’s unlikely that your pull request will be accepted as is. Please don’t submit pull requests that change existing behaviour. Instead, think about how you can add a new feature in a minimally invasive way.</p>
</div>
</div>
</div>
<div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
<nav id="toc" data-toggle="toc" class="sticky-top">
<h2 data-toc-skip>Contents</h2>
</nav>
</div>
</div>
<footer>
<div class="copyright">
<p>Developed by Nima Hejazi, Alan Hubbard, Mark van der Laan.</p>
</div>
<div class="pkgdown">
<p>Site built with <a href="https://pkgdown.r-lib.org/">pkgdown</a> 1.6.1.</p>
</div>
</footer>
</div>
</body>
</html>