-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathfile.contributing.html
496 lines (389 loc) · 27.4 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
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
<!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 — Ruby-2.6.10</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='.'>Ruby-2.6.10</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="file_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 id="label-Contributing+to+Ruby">Contributing to Ruby</h1>
<p>Ruby has a vast and friendly community with hundreds of people contributing to a thriving open-source ecosystem. This guide is designed to cover ways for participating in the development of CRuby.</p>
<p>There are plenty of ways for you to help even if you’re not ready to write code or documentation. You can help by reporting issues, testing patches, and trying out beta releases with your applications.</p>
<h2 id="label-How+To+Report">How To Report</h2>
<p>If you’ve encountered a bug in Ruby please report it to the redmine issue tracker available at <a href="#label-Reporting+Security+Issues">https://bugs.ruby-lang.org/ bugs.ruby-lang.org}. Do not report security vulnerabilities here, there is a <code>channel</a> for them.</p>
<p>There are a few simple steps you should follow in order to receive feedback on your ticket.</p>
<ul><li>
<p>If you haven’t already, {<a href="https://bugs.ruby-lang.org/account/register">bugs.ruby-lang.org/account/register</a> sign up for an account</code> on the bug tracker.</p>
</li><li>
<p>Try the latest version.</p>
<p>If you aren’t already using the latest version, try installing a newer stable release. See <a href="https://www.ruby-lang.org/en/downloads" target="_parent" title="/ Downloading Ruby">/ Downloading Ruby</a>.</p>
</li><li>
<p>Look to see if anyone already reported your issue, try <a href="https://bugs.ruby-lang.org/projects/ruby-trunk/issues" target="_parent" title="searching on redmine">searching on redmine</a> for your problem.</p>
</li><li>
<p>If you can’t find a ticket addressing your issue, <a href="https://bugs.ruby-lang.org/projects/ruby-trunk/issues/new" target="_parent" title="create a new one">create a new one</a>.</p>
</li><li>
<p>Choose the target version, usually current. Bugs will be first fixed in the current release and then <a href="#label-Backport+Requests">backported</a>.</p>
</li><li>
<p>Fill in the Ruby version you’re using when experiencing this issue (<code>ruby -v</code>).</p>
</li><li>
<p>Attach any logs or reproducible programs to provide additional information. Reproducible scripts should be as small as possible.</p>
</li><li>
<p>Briefly describe your problem. A 2-3 sentence description will help give a quick response.</p>
</li><li>
<p>Pick a category, such as core for common problems, or lib for a standard library.</p>
</li><li>
<p>Check the <a href="https://bugs.ruby-lang.org/projects/ruby/wiki/Maintainers" target="_parent" title="Maintainers list">Maintainers list</a> and assign the ticket if there is an active maintainer for the library or feature.</p>
</li><li>
<p>If the ticket doesn’t have any replies after 10 days, you can send a reminder.</p>
</li><li>
<p>Please reply to feedback requests. If a bug report doesn’t get any feedback, it’ll eventually get rejected.</p>
</li></ul>
<h3 id="label-Reporting+to+downstream+distributions">Reporting to downstream distributions</h3>
<p>You can report downstream issues for the following distributions via their bug tracker:</p>
<ul><li>
<p><a href="https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=ruby-defaults" target="_parent" title="debian">debian</a></p>
</li><li>
<p><a href="http://www.freebsd.org/cgi/query-pr-summary.cgi?text=ruby" target="_parent" title="freebsd">freebsd</a></p>
</li><li>
<p><a href="https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED" target="_parent" title="redhat">redhat</a></p>
</li><li>
<p><a href="https://trac.macports.org/query?status=assigned&status=new&status=reopened&port=~ruby" target="_parent" title="macports">macports</a></p>
</li><li>
<p>etc (add your distribution bug tracker here)</p>
</li></ul>
<h3 id="label-Platform+Maintainers">Platform Maintainers</h3>
<p>For platform specific bugs in Ruby, you can assign your ticket to the current maintainer for a specific platform.</p>
<p>The current active platform maintainers are as follows:</p>
<dl class="rdoc-list label-list"><dt>mswin64 (Microsoft Windows)
<dd>
<p>NAKAMURA Usaku (usa)</p>
</dd><dt>mingw32 (Minimalist GNU for Windows)
<dd>
<p>Nobuyoshi Nakada (nobu)</p>
</dd><dt>AIX
<dd>
<p>Yutaka Kanemoto (kanemoto)</p>
</dd><dt>FreeBSD
<dd>
<p>Akinori MUSHA (knu)</p>
</dd><dt>Solaris
<dd>
<p>Naohisa Goto (ngoto)</p>
</dd><dt>RHEL, CentOS
<dd>
<p>KOSAKI Motohiro (kosaki)</p>
</dd><dt>macOS
<dd>
<p>Kenta Murata (mrkn)</p>
</dd><dt>cygwin, bcc32, djgpp, wince, …
<dd>
<p>none. (Maintainer WANTED)</p>
</dd></dl>
<h2 id="label-Reporting+Security+Issues">Reporting Security Issues</h2>
<p>Security vulnerabilities receive special treatment since they may negatively affect many users. There is a private mailing list that all security issues should be reported to and will be handled discretely. Email the <a href="mailto:[email protected]">[email protected]</a> list and the problem will be published after fixes have been released. You can also encrypt the issue using <a href="https://www.ruby-lang.org/security.asc" target="_parent" title="the PGP public key">the PGP public key</a> for the list.</p>
<h2 id="label-Reporting+Other+Issues">Reporting Other Issues</h2>
<p>If you’re having an issue with the website, or maybe the mailing list, you can contact the webmaster to help resolve the problem.</p>
<p>The current webmaster is:</p>
<ul><li>
<p>Hiroshi SHIBATA (hsbt)</p>
</li></ul>
<p>You can also report issues with the ruby-lang.org website on the issue tracker:</p>
<ul><li>
<p><a href="https://github.com/ruby/www.ruby-lang.org/issues" target="_parent" title="issue tracker">issue tracker</a></p>
</li></ul>
<h2 id="label-Resolve+Existing+Issues">Resolve Existing Issues</h2>
<p>As a next step beyond reporting issues you can help the core team resolve existing issues. If you check the Everyone’s Issues list in GitHub Issues, you will find a lot of issues already requiring attention. What can you do for these? Quite a bit, actually:</p>
<p>When a bug report goes for a while without any feedback, it goes to the bug graveyard which is unfortunate. If you check the <a href="https://bugs.ruby-lang.org/projects/ruby-trunk/issues" target="_parent" title="issues list">issues list</a> you will find lots of delinquent bugs that require attention.</p>
<p>You can help by verifying the existing tickets, try to reproduce the reported issue on your own and comment if you still experience the bug. Some issues lack attention because of too much ambiguity, to help you can narrow down the problem and provide more specific details or instructions to reproduce the bug. You might also try contributing a failing test in the form of a patch, which we will cover later in this guide.</p>
<p>It may also help to try out patches other contributors have submitted to redmine, if gone without notice. In this case the <code>patch</code> command is your friend, see <code>man patch</code> for more information. Basically this would go something like this:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_cd'>cd</span> <span class='id identifier rubyid_path'>path</span><span class='op'>/</span><span class='id identifier rubyid_to'>to</span><span class='op'>/</span><span class='id identifier rubyid_ruby'>ruby</span><span class='op'>/</span><span class='id identifier rubyid_trunk'>trunk</span>
<span class='id identifier rubyid_patch'>patch</span> <span class='op'>-</span><span class='id identifier rubyid_p0'>p0</span> <span class='op'><</span> <span class='id identifier rubyid_path'>path</span><span class='op'>/</span><span class='id identifier rubyid_to'>to</span><span class='op'>/</span><span class='id identifier rubyid_patch'>patch</span></code></pre>
<p>You will then be prompted to apply the patch with the associated files. After building ruby again, you should try to run the tests and verify if the change actually worked or fixed the bug. It’s important to provide valuable feedback on the patch that can help reach the overall goal, try to answer some of these questions:</p>
<ul><li>
<p>What do you like about this change?</p>
</li><li>
<p>What would you do differently?</p>
</li><li>
<p>Are there any other edge cases not tested?</p>
</li><li>
<p>Is there any documentation that would be affected by this change?</p>
</li></ul>
<p>If you can answer some or all of these questions, you’re on the right track. If your comment simply says “+1”, then odds are that other reviewers aren’t going to take it too seriously. Show that you took the time to review the patch.</p>
<h2 id="label-How+To+Request+Features">How To Request Features</h2>
<p>If there’s a new feature that you want to see added to Ruby, you will need to write a convincing proposal and patch to implement the feature.</p>
<p>For new features in CRuby, use the <a href="https://bugs.ruby-lang.org/projects/ruby-trunk/issues?set_filter=1&tracker_id=2" target="_parent" title="‘Feature’ tracker">‘Feature’ tracker</a> on ruby-trunk. For non-CRuby dependent features, features that would apply to alternate Ruby implementations such as JRuby and Rubinius, use the <a href="https://bugs.ruby-lang.org/projects/common-ruby" target="_parent" title="CommonRuby tracker">CommonRuby tracker</a>.</p>
<p>When writing a proposal be sure to check for previous discussions on the topic and have a solid use case. You will need to be persuasive and convince Matz on your new feature. You should also consider the potential compatibility issues that this new feature might raise.</p>
<p>Consider making your feature into a gem, and if there are enough people who benefit from your feature it could help persuade ruby-core. Although feature requests can seem like an alluring way to contribute to Ruby, often these discussions can lead nowhere and exhaust time and energy that could be better spent fixing bugs. Choose your battles.</p>
<p>A good template for a feature proposal should look something like this:</p>
<dl class="rdoc-list label-list"><dt>Abstract
<dd>
<p>Summary of your feature</p>
</dd><dt>Background
<dd>
<p>Describe current behavior and why it is problem. Related work, such as solutions in other language helps us to understand the problem.</p>
</dd><dt>Proposal
<dd>
<p>Describe your proposal in details</p>
</dd><dt>Details
<dd>
<p>If it has complicated feature, describe it</p>
</dd><dt>Usecase
<dd>
<p>How would your feature be used? Who will benefit from it?</p>
</dd><dt>Discussion
<dd>
<p>Discuss about this proposal. A list of pros and cons will help start discussion.</p>
</dd><dt>Limitation
<dd>
<p>Limitation of your proposal</p>
</dd><dt>Another alternative proposal
<dd>
<p>If there are alternative proposals, show them.</p>
</dd><dt>See also
<dd>
<p>Links to the other related resources</p>
</dd></dl>
<h3 id="label-Slideshow">Slideshow</h3>
<p>At the Ruby Developer Meeting in Japan, committers discuss Feature Proposals together in Tokyo. We will judge proposals and then accept, reject, or give feedback for them. If you have a stalled proposal, making a slide to submit is good way to get feedback.</p>
<p>Slides should be:</p>
<ul><li>
<p>One-page slide</p>
</li><li>
<p>Include a corresponding ticket number</p>
</li><li>
<p>MUST include a figure and/or short example code</p>
</li><li>
<p>SHOULD have less sentence in natural language (try to write less than 140 characters)</p>
</li><li>
<p>It is RECOMMENDED to itemize: motivation/use case, proposal, pros/cons, corner case</p>
</li><li>
<p>PDF or Image (Web browsers can show it)</p>
</li></ul>
<p>Please note:</p>
<ul><li>
<p>Even if the proposal is generally acceptable, it won’t be accepted without writing corner cases in the ticket</p>
</li><li>
<p>Slide’s example: DevelopersMeeting20130727Japan</p>
</li></ul>
<h2 id="label-Backport+Requests">Backport Requests</h2>
<p>When a new version of Ruby is released, it starts at patch level 0 (p0), and bugs will be fixed first on the trunk branch. If it’s determined that a bug exists in a previous version of Ruby that is still in the bug fix stage of maintenance, then a patch will be backported. After the maintenance stage of a particular Ruby version ends, it goes into “security fix only” mode which means only security related vulnerabilities will be backported. Versions in End-of-life (EOL) will not receive any updates and it is recommended you upgrade as soon as possible.</p>
<p>If a major security issue is found or after a certain amount of time since the last patch level release, a new patch-level release will be made.</p>
<p>When submitting a backport request please confirm the bug has been fixed in newer versions and exists in maintenance mode versions. There is a backport tracker for each major version still in maintenance where you can request a particular revision merged in the affected version of Ruby.</p>
<p>Each major version of Ruby has a release manager that should be assigned to handle backport requests. You can find the list of release managers on the <a href="https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering" target="_parent" title="wiki">wiki</a>.</p>
<h3 id="label-Branches">Branches</h3>
<p>Status and maintainers of branches are listed on the <a href="https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering" target="_parent" title="wiki">wiki</a>.</p>
<h2 id="label-Running+tests">Running tests</h2>
<p>In order to help resolve existing issues and contributing patches to Ruby you need to be able to run the test suite.</p>
<p>CRuby uses subversion for source control, you can find installation instructions and lots of great info to learn subversion on the <a href="http://svnbook.red-bean.com" target="_parent" title="/ svnbook.red-bean.com">/ svnbook.red-bean.com</a>. For other resources see the <a href="https://www.ruby-lang.org/en/community/ruby-core" target="_parent" title="/ ruby-core documentation on ruby-lang.org">/ ruby-core documentation on ruby-lang.org</a>.</p>
<p>This guide will use git for contributing. The <a href="https://git-scm.com" target="_parent" title="/ git homepage">/ git homepage</a> has installation instructions with links to documentation for learning more about git. There is a mirror of the subversion repository on <a href="https://github.com/ruby/ruby" target="_parent" title="github">github</a>.</p>
<p>Install the prerequisite dependencies for building the CRuby interpreter to run tests.</p>
<ul><li>
<p>C compiler</p>
</li><li>
<p>autoconf</p>
</li><li>
<p>bison</p>
</li><li>
<p>gperf</p>
</li><li>
<p>ruby - Ruby itself is prerequisite in order to build Ruby from source. It can be 1.8.</p>
</li></ul>
<p>You should also have access to development headers for the following libraries, but these are not required:</p>
<ul><li>
<p>Tcl/Tk</p>
</li><li>
<p>NDBM/QDBM</p>
</li><li>
<p>GDBM</p>
</li><li>
<p>OpenSSL</p>
</li><li>
<p>readline/editline(libedit)</p>
</li><li>
<p>zlib</p>
</li><li>
<p>libffi</p>
</li><li>
<p>libyaml</p>
</li><li>
<p>libexecinfo (FreeBSD)</p>
</li></ul>
<p>Now let’s build CRuby:</p>
<ul><li>
<p>Checkout the CRuby source code:</p>
<pre class="code ruby"><code class="ruby">git clone https://github.com/ruby/ruby.git ruby-trunk</code></pre>
</li><li>
<p>Generate the configuration files and build:</p>
<pre class="code ruby"><code class="ruby">cd ruby-trunk
autoconf
mkdir build && cd build # its good practice to build outside of source dir
mkdir ~/.rubies # we will install to .rubies/ruby-trunk in our home dir
#../configure --prefix="${HOME}/.rubies/ruby-trunk"
make up && make install</code></pre>
</li></ul>
<p>After adding Ruby to your PATH, you should be ready to run the test suite:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='id identifier rubyid_test'>test</span></code></pre>
<p>You can also use <code>test-all</code> to run all of the tests with the RUNRUBY interpreter just built. Use TESTS or RUNRUBYOPT to pass parameters, such as:</p>
<pre class="code ruby"><code class="ruby">make test-all TESTS=-v</code></pre>
<p>This is also how you can run a specific test from our build dir:</p>
<pre class="code ruby"><code class="ruby">make test-all TESTS=drb/test_drb.rb</code></pre>
<p>You can run <code>test</code> and <code>test-all</code> at once by <code>check</code> .</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='id identifier rubyid_check'>check</span></code></pre>
<p>For older versions of Ruby you will need to run the build setup again after checking out the associated branch in git, for example if you wanted to checkout 1.9.3:</p>
<pre class="code ruby"><code class="ruby">git clone https://github.com/ruby/ruby.git --branch ruby_1_9_3</code></pre>
<p>Once you checked out the source code, you can update the local copy by:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='id identifier rubyid_up'>up</span></code></pre>
<p>Or, update, build, install and check, by just:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_make'>make</span> <span class='id identifier rubyid_love'>love</span></code></pre>
<h2 id="label-Contributing+Documentation">Contributing Documentation</h2>
<p>If you’re interested in contributing documentation directly to CRuby there is some information available at <a href="https://github.com/ruby/ruby#contributing" target="_parent" title="Contributing">Contributing</a>.</p>
<p>There is also the <a href="https://github.com/rurema/doctree/wiki" target="_parent" title="Ruby Reference Manual">Ruby Reference Manual</a> in Japanese.</p>
<h2 id="label-Contributing+A+Patch">Contributing A Patch</h2>
<h3 id="label-Deciding+what+to+patch">Deciding what to patch</h3>
<p>Before you submit a patch, there are a few things you should know:</p>
<ul><li>
<p>Pay attention to the maintenance policy for stable and maintained versions of Ruby.</p>
</li><li>
<p>Released versions in security mode will not merge feature changes.</p>
</li><li>
<p>Search for previous discussions on ruby-core to verify the maintenance policy</p>
</li><li>
<p>Patches must be distributed under Ruby’s license.</p>
</li><li>
<p>This license may change in the future, you must join the discussion if you don’t agree to the change</p>
</li></ul>
<p>To improve the chance your patch will be accepted please follow these simple rules:</p>
<ul><li>
<p>Bug fixes should be committed on trunk first</p>
</li><li>
<p>Format of the patch file must be a unified diff (ie: diff -pu, svn diff, or git diff)</p>
</li><li>
<p>Don’t introduce cosmetic changes</p>
</li><li>
<p>Follow the original coding style of the code</p>
</li><li>
<p>Don’t mix different changes in one commit</p>
</li></ul>
<p>First thing you should do is check out the code if you haven’t already:</p>
<pre class="code ruby"><code class="ruby">git clone https://github.com/ruby/ruby.git ruby-trunk</code></pre>
<p>Now create a dedicated branch:</p>
<pre class="code ruby"><code class="ruby">cd ruby-trunk
git checkout -b my_new_branch</code></pre>
<p>The name of your branch doesn’t really matter because it will only exist on your local computer and won’t be part of the official Ruby repository. It will be used to create patches based on the differences between your branch and trunk, or edge Ruby.</p>
<h3 id="label-Coding+style">Coding style</h3>
<p>Here are some general rules to follow when writing Ruby and C code for CRuby:</p>
<ul><li>
<p>Indent 4 spaces for C without tabs (old codes might use tabs for eight-space indentation, but newer codes recommend to use spaces only)</p>
</li><li>
<p>Indent 2 space tabs for Ruby</p>
</li><li>
<p>Do not use TABs in ruby codes</p>
</li><li>
<p>ANSI C style for 1.9+ for function declarations</p>
</li><li>
<p>Follow C90 (not C99) Standard</p>
</li><li>
<p>PascalStyle for class/module names.</p>
</li><li>
<p>UNDERSCORE_SEPARATED_UPPER_CASE for other constants.</p>
</li><li>
<p>Capitalize words.</p>
</li><li>
<p>ABBRs should be all upper case.</p>
</li><li>
<p>Do as others do</p>
</li></ul>
<h3 id="label-ChangeLog">ChangeLog</h3>
<p>Although not required, if you wish to add a ChangeLog entry for your change please note:</p>
<p>You can use the following template for the ChangeLog entry on your commit:</p>
<pre class="code ruby"><code class="ruby">Thu Jan 1 00:00:00 2004 Your Name <[email protected]>
* filename (function): short description of this commit.
This should include your intention of this change.
[bug:#number] [mailinglist:number]
* filename2 (function2): additional description for this file/function.</code></pre>
<p>This follows <a href="http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs" target="_parent" title="GNU Coding Standards for Change Logs">GNU Coding Standards for Change Logs</a>, some other requirements and tips:</p>
<ul><li>
<p>Timestamps must be in JST (+09:00) in the style as above.</p>
</li><li>
<p>Two spaces between the timestamp and your name. Two spaces between your name and your mail address.</p>
</li><li>
<p>One blank line between the timestamp and the description.</p>
</li><li>
<p>Indent the description with TAB. 2nd line should begin with TAB+2SP.</p>
</li><li>
<p>Write a entry (*) for each change.</p>
</li><li>
<p>Refer to redmine issue or discussion on the mailing list.</p>
</li><li>
<p>For GitHub issues, use [GH-#] (such as [Fixes GH-234]</p>
</li><li>
<p>One blank line between entries.</p>
</li><li>
<p>Do as other committers do.</p>
</li></ul>
<p>You can generate the ChangeLog entry by running <code>make change</code></p>
<p>When you’re ready to commit, copy your ChangeLog entry into the commit message, keeping the same formatting and select your files:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_git'>git</span> <span class='id identifier rubyid_commit'>commit</span> <span class='const'>ChangeLog</span> <span class='id identifier rubyid_path'>path</span><span class='op'>/</span><span class='id identifier rubyid_to'>to</span><span class='op'>/</span><span class='id identifier rubyid_files'>files</span></code></pre>
<p>In the likely event that your branch becomes outdated, you will have to update your working branch:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_git'>git</span> <span class='id identifier rubyid_fetch'>fetch</span> <span class='id identifier rubyid_origin'>origin</span>
<span class='id identifier rubyid_git'>git</span> <span class='id identifier rubyid_rebase'>rebase</span> <span class='id identifier rubyid_remotes'>remotes</span><span class='op'>/</span><span class='id identifier rubyid_origin'>origin</span><span class='op'>/</span><span class='id identifier rubyid_master'>master</span></code></pre>
<p>Now that you’ve got some code you want to contribute, let’s get set up to generate a patch. Start by forking the github mirror, check the <a href="https://help.github.com/articles/fork-a-repo" target="_parent" title="github docs on forking">github docs on forking</a> if you get stuck here. You will only need a github account if you intend to host your repository on github.</p>
<p>Next copy the writable url for your fork and add it as a git remote, replace “my_username” with your github account name:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_git'>git</span> <span class='id identifier rubyid_remote'>remote</span> <span class='id identifier rubyid_add'>add</span> <span class='id identifier rubyid_my_fork'>my_fork</span> <span class='id identifier rubyid_git'>git</span><span class='ivar'>@github</span>.<span class='id identifier rubyid_com'>com</span><span class='symbeg'>:</span><span class='id identifier rubyid_my_username'>my_username</span><span class='op'>/</span><span class='id identifier rubyid_ruby'>ruby</span>.<span class='id identifier rubyid_git'>git</span>
<span class='comment'># Now we can push our branch to our fork
</span><span class='id identifier rubyid_git'>git</span> <span class='id identifier rubyid_push'>push</span> <span class='id identifier rubyid_my_fork'>my_fork</span> <span class='id identifier rubyid_my_new_branch'>my_new_branch</span></code></pre>
<p>In order to generate a patch that you can upload to the bug tracker, we can use the github interface to review our changes just visit <a href="https://github.com/my_username/ruby/compare/trunk...my_new_branch">github.com/my_username/ruby/compare/trunk…my_new_branch</a></p>
<p>Next, you can simply add ‘.patch’ to the end of this URL and it will generate the patch for you, save the file to your computer and upload it to the bug tracker. Alternatively you can submit a pull request, but for the best chances to receive feedback add it is recommended you add it to redmine.</p>
<p>Since git is a distributed system, you are welcome to host your git repository on any <a href="https://git.wiki.kernel.org/index.php/GitHosting" target="_parent" title="publicly accessible hosting site">publicly accessible hosting site</a>, including <a href="https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories" target="_parent" title="hosting your own">hosting your own</a> You may use the <a href="https://git-scm.com/docs/git-format-patch" target="_parent" title="‘git format-patch’">‘git format-patch’</a> command to generate patch files to upload to redmine. You may also use the <a href="https://git-scm.com/docs/git-request-pull" target="_parent" title="‘git request-pull’">‘git request-pull’</a> command for formatting pull request messages to redmine.</p>
<div id='footer'></div>
</div> <!-- content -->
</div> <!-- y_main -->
</body>
</html>