-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathfile.CONTRIBUTING.html
286 lines (189 loc) · 14.9 KB
/
file.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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
<!DOCTYPE html>
<html>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, user-scalable=no'>
<meta name='apple-touch-fullscreen' content='yes'>
<meta name='apple-mobile-web-app-capable' content='yes'>
<meta name='apple-mobile-web-app-status-bar-style' content='rgba(228,228,228,1.0)'>
<title>File: CONTRIBUTING — Puma master</title>
<link rel='stylesheet' type='text/css' href='../css/y_fonts.css' />
<link rel='stylesheet' type='text/css' href='../css/highlight.github.css' />
<link rel='stylesheet' type='text/css' href='../css/y_style.css' />
<link rel='stylesheet' type='text/css' href='../css/y_list.css' />
<link rel='stylesheet' type='text/css' href='../css/y_color.css' />
<script type='text/javascript'>
var pathId = "CONTRIBUTING",
relpath = '';
var t2Info = {
CSEP: '.',
ISEP: '#',
NSEP: '::'
};
</script>
<script type='text/javascript' charset='utf-8' src='../js/highlight.pack.js'></script>
<script type='text/javascript' charset='utf-8' src='../js/y_app.js'></script>
</head>
<body>
<svg id='y_wait' class viewBox='0 0 90 90'></svg>
<div id='settings' class='hidden'></div>
<div id='y_list' class='d h'>
<header id='list_header'></header>
<nav id= 'list_nav' class='y_nav l_nav'>
<ul id='list_items'></ul>
</nav>
</div>
<div id='y_toc' class='f h'>
<header id='toc_header'></header>
<nav id= 'toc_nav' class='y_nav t_nav'>
<ol id='toc_items'></ol>
</nav>
</div>
<div id='y_main' tabindex='-1'>
<header id='y_header'>
<div id='y_menu'>
<a id='home_no_xhr' href='/'>Home</a> »
<a href='.'>Puma master</a> »
<a href='_index.html'>Index</a> »
<span class='title'><a id='t2_doc_top' href='#'>File: CONTRIBUTING ▲</a></span>
</div>
<a id='list_href' href="class_list.html"></a>
<div id='y_measure_em' class='y_measure'></div>
<div id='y_measure_vh' class='y_measure'></div>
<span id='y_measure_50pre' class='y_measure'><code>123456789_123456789_123456789_123456789_123456789_</code></span>
</header>
<div id='content' class='file'>
<h1>Contributing to <a href="Puma.html" title="Puma (module)"><code>Puma</code></a></h1>
<p>By participating in this project, you agree to follow the <a href="https://github.com/puma/puma/blob/master/CODE_OF_CONDUCT.md">code of conduct</a>.</p>
<p>There are lots of ways to contribute to <a href="Puma.html" title="Puma (module)"><code>Puma</code></a>. Some examples include:</p>
<ul>
<li>creating a <a href="https://github.com/puma/puma/issues/new?template=bug_report.md">bug report</a> or <a href="https://github.com/puma/puma/issues/new?template=feature_request.md">feature request</a></li>
<li>verifying <a href="https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Aneeds-repro">existing bug reports</a> and adding <a href="https://github.com/puma/puma/blob/CONTRIBUTING.md#reproduction-steps">reproduction steps</a></li>
<li>reviewing <a href="https://github.com/puma/puma/pulls">pull requests</a> and testing the changes locally on your machine</li>
<li>writing or editing <a href="https://github.com/puma/puma/tree/master/docs">documentation</a></li>
<li>improving test coverage</li>
<li>fixing a <a href="https://github.com/puma/puma/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Abug">reproducing bug</a> or adding a new feature</li>
</ul>
<p>Newbies welcome! We would be happy to help you make your first contribution to a F/OSS project.</p>
<h2>Setup</h2>
<p>Any questions about contributing may be asked in our <a href="https://github.com/puma/puma/discussions">Discussions</a>.</p>
<p><strong>If you're nervous, get stuck, need help, or want to know where to start and where you can help</strong>, please don't hesitate to <a href="https://calendly.com/nateberkopec/30min">book 30 minutes with maintainer @nateberkopec here</a>. He is happy to help!</p>
<p>Nate also <a href="https://www.youtube.com/watch?v=w4X_oBuPmTM">gave a 40 minute conference talk in 2022</a> detailing how <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> works, a brief overview of its internals, and a quick guide on how to contribute.</p>
<h4>Clone the repo</h4>
<p>Clone the <a href="Puma.html" title="Puma (module)"><code>Puma</code></a> repository:</p>
<pre class="code sh"><code class="sh">git clone [email protected]:puma/puma.git && cd puma
</code></pre>
<h4>Ragel</h4>
<p>You need to install <a href="use%20Ragel%20version%207.0.0.9">ragel</a> to generate Puma's extension code.</p>
<p>macOS:</p>
<pre class="code sh"><code class="sh">brew install ragel
</code></pre>
<p>Linux:</p>
<pre class="code sh"><code class="sh">apt-get install ragel
</code></pre>
<p>Windows (Ruby 2.5 and later):</p>
<pre class="code sh"><code class="sh">ridk exec pacman -S mingw-w64-x86_64-openssl mingw-w64-x86_64-ragel
</code></pre>
<h4>Install Ruby dependencies</h4>
<p>Install the Ruby dependencies:</p>
<pre class="code sh"><code class="sh">bundle install
</code></pre>
<h4>Compile the native extensions</h4>
<p>To run Puma locally, you must compile the native extension. Running the <code>test</code> rake task does this automatically, but you may need to manually run the compile command if you want to run Puma and haven't run the tests yet:</p>
<p>Ubuntu, macOS, etc:</p>
<pre class="code sh"><code class="sh">bundle exec rake compile
</code></pre>
<p>Windows:</p>
<pre class="code sh"><code class="sh">bundle exec rake -rdevkit compile
</code></pre>
<h4>Run your local Puma</h4>
<p>Now, you should be able to run Puma locally:</p>
<pre class="code sh"><code class="sh">bundle exec bin/puma test/rackup/hello.ru
# -or-
bundle exec ruby -Ilib bin/puma test/rackup/hello.ru
</code></pre>
<p>Alternatively, you can reference your local copy in a project's <code>Gemfile</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>puma</span><span class='tstring_end'>"</span></span><span class='comma'>,</span> <span class='label'>path:</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>/path/to/local/puma</span><span class='tstring_end'>"</span></span></code></pre>
<p>See the <a href="https://bundler.io/man/gemfile.5.html#PATH">Bundler docs</a> for more details.</p>
<h2>Running tests</h2>
<p>To run rubocop + tests:</p>
<pre class="code sh"><code class="sh">bundle exec rake
</code></pre>
<p>To run the test suite only:</p>
<pre class="code sh"><code class="sh">bundle exec rake test
</code></pre>
<p>To run a single test file:</p>
<pre class="code sh"><code class="sh">bundle exec ruby test/test_binder.rb
</code></pre>
<p>You can also run tests with <a href="https://github.com/qrush/m"><code>m</code></a>:</p>
<pre class="code sh"><code class="sh">bundle exec m test/test_binder.rb
</code></pre>
<p>To run a single test:</p>
<pre class="code sh"><code class="sh">bundle exec m test/test_binder.rb:37
</code></pre>
<p>To run a single test with 5 seconds as the test case timeout:</p>
<pre class="code sh"><code class="sh">TEST_CASE_TIMEOUT=5 bundle exec m test/test_binder.rb:37
</code></pre>
<p>If you would like more information about extension building, SSL versions, your local Ruby version, and more, use the PUMA_TEST_DEBUG env variable:</p>
<pre class="code sh"><code class="sh">PUMA_TEST_DEBUG=1 bundle exec rake test
</code></pre>
<p>Puma also has a helper file for running tests, see the comments at the top of the <code>test/runner</code> file. Example:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_test'>test</span><span class='op'>/</span><span class='id identifier rubyid_runner'>runner</span> <span class='op'>-</span><span class='id identifier rubyid_v'>v</span> <span class='id identifier rubyid_test_puma_server'>test_puma_server</span>.<span class='id identifier rubyid_rb'>rb</span></code></pre>
<h4>File limits</h4>
<p>Puma's test suite opens up a lot of sockets. This may exceed the default limit of your operating system. If your file limits are low, you may experience "too many open file" errors when running the Puma test suite.</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># check your file limit
</span><span class='id identifier rubyid_ulimit'>ulimit</span> <span class='op'>-</span><span class='const'>S</span> <span class='op'>-</span><span class='id identifier rubyid_n'>n</span>
<span class='comment'># change file limit for the current session
</span><span class='id identifier rubyid_ulimit'>ulimit</span> <span class='op'>-</span><span class='const'>S</span> <span class='op'>-</span><span class='id identifier rubyid_n'>n</span> <span class='op'><</span><span class='id identifier rubyid_value'>value</span><span class='op'>></span></code></pre>
<p>We find that values of 4000 or more work well. <a href="https://wilsonmar.github.io/maximum-limits/">Learn more about your file limits and how to change them here.</a></p>
<h2>How to contribute</h2>
<p>Puma could use your help in several areas!</p>
<p><strong>Don't worry about "claiming an issue". No issues are "claimed" in Puma.</strong> Just start working on it. The issue tracker is almost always kept updated, so if there is an open issue, it is ready for you to contribute (unless you have questions about how to close issue - then please ask!). Once you have a few lines of code, post a draft PR. We are more than happy to help once you have a draft PR up.</p>
<p><strong>New to systems programming? That's ok!</strong> Puma deals with concepts you may not have been familiar with before, like sockets, TCP, UDP, SSL, and Threads. That's ok! You can learn by contributing. Also, see the "Bibliography" section at the end of this document.</p>
<p><strong>The <a href="https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Acontrib-wanted">contrib-wanted</a> label indicates that an issue might approachable to first-time contributors.</strong></p>
<p><strong>Reproducing bug reports</strong>: The <a href="https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Aneeds-repro">needs-repro</a> label indicates than an issue lacks reproduction steps. You can help by reproducing the issue and sharing the steps you took in the comments.</p>
<p><strong>Helping with our native extensions</strong>: If you are interested in writing C or Java, we could really use your help. Check out the issue labels for <a href="https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Ac-ext">c-ext</a> and <a href="https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Ajruby">JRuby</a>.</p>
<p><strong>Fixing bugs</strong>: Issues with the <a href="https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Abug">bug</a> label have working reproduction steps, which you can use to write a test and submit a patch.</p>
<p><strong>Writing features</strong>: The <a href="https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Afeature">feature</a> label highlights requests for new functionality. Write tests and code up our new feature!</p>
<p><strong>Code review</strong>: Take a look at open pull requests and offer your feedback. Code review is not just for maintainers. We need your help and eyeballs!</p>
<p><strong>Write documentation</strong>: Puma needs more docs in many areas, especially where we have open issues with the <a href="https://github.com/puma/puma/issues?q=is%3Aopen+is%3Aissue+label%3Adocs">docs</a> label.</p>
<h2>Reproduction steps</h2>
<p>Reproducing a bug helps identify the root cause of that bug so it can be fixed.</p>
<p>To get started, create a rackup file and config file and then run your test app
with:</p>
<pre class="code sh"><code class="sh">bundle exec puma -C <path/to/config.rb> <path/to/rackup.ru>
</code></pre>
<p>For example, using a test rack app (<a href="https://github.com/puma/puma/blob/master/test/rackup/hello.ru"><code>test/rackup/hello.ru</code></a>) and a
test config file (<a href="https://github.com/puma/puma/blob/master/test/config/settings.rb"><code>test/config/settings.rb</code></a>):</p>
<pre class="code sh"><code class="sh">bundle exec puma -C test/config/settings.rb test/rackup/hello.ru
</code></pre>
<p>There is also a Dockerfile available for reproducing Linux-specific issues:</p>
<pre class="code sh"><code class="sh">docker build -f tools/Dockerfile -t puma .
docker run -p 9292:9292 -it puma
</code></pre>
<h2>Pull requests</h2>
<p>Please open draft PRs as soon as you are ready for feedback from the community.</p>
<p>Code contributions should generally include test coverage. If you aren't sure how to
test your changes, please open a pull request and leave a comment asking for
help.</p>
<p>There's no need to update the changelog (<a href="file.History.html"><code>History.md</code></a>); that is done <a href="file.Release.html">when a new release is made</a>.</p>
<p>Puma uses <a href="https://docs.github.com/en/actions">GitHub Actions</a> for CI testing. Please consider running the workflows in your fork before creating a PR. It is possible to enable GitHub Actions on your fork in the repositories' <code>Actions</code> tab.</p>
<h2>Backports</h2>
<p>Puma does not have a backport "policy" - maintainers will not consistently backport bugfixes to previous minor or major versions (we do treat security differently, see <a href="file.SECURITY.html"><code>SECURITY.md</code></a>.</p>
<p>As a contributor, you may make pull requests against <code>-stable</code> branches to backport fixes, and maintainers will release them once they're merged. For example, if you'd like to make a backport for 4.3.x, you can make a pull request against <code>4-3-stable</code>. If there is no appropriate branch for the release you'd like to backport against, please just open an issue and we'll make one for you.</p>
<h2>Join the community</h2>
<p>If you're looking to contribute to Puma, please join us in <a href="https://github.com/puma/puma/discussions">Discussions</a>.</p>
<h2>Bibliography/Reading</h2>
<p>Puma can be a bit intimidating for your first contribution because there's a lot of concepts here that you've probably never had to think about before - Rack, sockets, forking, threads etc. Here are some helpful links for learning more about things related to Puma:</p>
<ul>
<li>[Puma's Architecture docs])</li>
<li><a href="https://github.com/rack/rack/blob/master/SPEC.rdoc">The Rack specification</a></li>
<li><a href="https://workingwithruby.com/">Working with...</a> "Working With" is a excellent (and now free) Ruby book series about working with Threads, TCP and Unix Sockets.</li>
<li>The Ruby docs for IO.pipe, TCPServer/Socket.</li>
<li><a href="https://github.com/socketry/nio4r/wiki/Getting-Started">nio4r documentation</a></li>
</ul>
<div id='footer'></div>
</div> <!-- content -->
</div> <!-- y_main -->
</body>
</html>