/usr/share/doc/racket/style/branch-and-commit.html is in racket-doc 6.1-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>7 Retiquette: Branch and Commit</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">How to Program Racket</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="correct-maintain-speed.html" class="tocviewlink" data-pltdoc="x">Basic Facts of Life</a></td></tr><tr><td align="right">2 </td><td><a href="testing.html" class="tocviewlink" data-pltdoc="x">Testing</a></td></tr><tr><td align="right">3 </td><td><a href="Units_of_Code.html" class="tocviewlink" data-pltdoc="x">Units of Code</a></td></tr><tr><td align="right">4 </td><td><a href="Choosing_the_Right_Construct.html" class="tocviewlink" data-pltdoc="x">Choosing the Right Construct</a></td></tr><tr><td align="right">5 </td><td><a href="Textual_Matters.html" class="tocviewlink" data-pltdoc="x">Textual Matters</a></td></tr><tr><td align="right">6 </td><td><a href="Language_and_Performance.html" class="tocviewlink" data-pltdoc="x">Language and Performance</a></td></tr><tr><td align="right">7 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Retiquette:<span class="mywbr"> </span> Branch and Commit</a></td></tr><tr><td align="right">8 </td><td><a href="Acknowledgment.html" class="tocviewlink" data-pltdoc="x">Acknowledgment</a></td></tr><tr><td align="right">9 </td><td><a href="Todo_List__Call_for_Contributions.html" class="tocviewlink" data-pltdoc="x">Todo List, Call for Contributions</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>7 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Retiquette:<span class="mywbr"> </span> Branch and Commit</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">7.1 </td><td><a href="#%28part._.Bugfix_.Workflow%29" class="tocviewlink" data-pltdoc="x">Bugfix Workflow</a></td></tr><tr><td align="right">7.2 </td><td><a href="#%28part._.Commit%29" class="tocviewlink" data-pltdoc="x">Commit</a></td></tr><tr><td align="right">7.3 </td><td><a href="#%28part._.No_.Commit__.Bombs___.Please%29" class="tocviewlink" data-pltdoc="x">No Commit “Bombs,” Please</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">7.1<tt> </tt></span><a href="#%28part._.Bugfix_.Workflow%29" class="tocsubseclink" data-pltdoc="x">Bugfix Workflow</a></td></tr><tr><td><span class="tocsublinknumber">7.2<tt> </tt></span><a href="#%28part._.Commit%29" class="tocsubseclink" data-pltdoc="x">Commit</a></td></tr><tr><td><span class="tocsublinknumber">7.3<tt> </tt></span><a href="#%28part._.No_.Commit__.Bombs___.Please%29" class="tocsubseclink" data-pltdoc="x">No Commit “Bombs,” Please</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="Language_and_Performance.html" title="backward to "6 Language and Performance"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "How to Program Racket"" data-pltdoc="x">up</a> <a href="Acknowledgment.html" title="forward to "8 Acknowledgment"" data-pltdoc="x">next →</a></span> </div><h3 x-source-module="(lib "scribblings/style/style.scrbl")" x-part-tag=""branch-and-commit"">7<tt> </tt><a name="(part._branch-and-commit)"></a>Retiquette: Branch and Commit</h3><p>This section is specifically for Racketeers who commit to the Racket code
base.</p><p>Working with the bug database requires one critical work flow rule.</p><p>Working with the code base requires style rules for actions on the
repository. Currently we are using Git and below are a few rules on how to
act in this context.</p><h4 x-source-module="(lib "scribblings/style/style.scrbl")" x-part-tag=""Bugfix_Workflow"">7.1<tt> </tt><a name="(part._.Bugfix_.Workflow)"></a>Bugfix Workflow</h4><p>Re-assign bug reports only after you can eliminate your own code as the source
of a bug. The best way to accomplish this goal is to create a new example that
re-creates the problem without involvement of your code. When you have such a
code snippet, re-assign the code to the person responsible for the apparently
buggy component and submit the code snippet as part of the justification.</p><h4 x-source-module="(lib "scribblings/style/style.scrbl")" x-part-tag=""Commit"">7.2<tt> </tt><a name="(part._.Commit)"></a>Commit</h4><p><span style="font-weight: bold">New feature commit:</span> Commit the new feature, its tests, and its
documentations as you wish, but please push them together. However, do not
commit states that don’t run. (In Git, this means ’commit’ and not just
’push’.)</p><p><span style="font-weight: bold">Bug fix commit:</span> When you fix a bug, make sure to commit (1) the
code delta, (2) the new test case, and (3) the revised docs (if
applicable) in one batch. If the creation of a single commit is too
complex of if you wish to factor out one of the commits, please push all
pieces at once. That way the code base is always in a state where code,
tests, and documentation are in sync, and readers of commit messages can
evaluate changes completely.</p><p><span style="font-weight: bold">Style change commit:</span> Submit changes to the style of a file
separately from changes to its behavior (new features, bugs).</p><p><div class="SIntrapara">Write meaningful commit messages. The first line (say 72 chars) should
provide a concise summary of the commit. If the message must be longer,
edit the rest of the message in your text editor and leave a blank line
between the summary line and the rest of the message, like this:
</div><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="hspace"> </span><span class="stt">some quick description</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">more blah blah blah, with more</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">details about the actual change</span></p></td></tr></table></div><div class="SIntrapara">The advantage of a blank line is that “git log” and other tools display
the commit messages properly. If you prefer the “-m” command line flag
over an editor, you can use several of them in a row.</div></p><p>The message for bug report fixes should contain “Close PR NNNNN” so that
bug reports are automatically closed.</p><p>To avoid ’merge commits’, update your repository with <span class="stt">git </span><span class="stt">–</span><span class="stt">rebase pull</span>.</p><h4 x-source-module="(lib "scribblings/style/style.scrbl")" x-part-tag=""No_Commit__Bombs___Please"">7.3<tt> </tt><a name="(part._.No_.Commit__.Bombs___.Please)"></a>No Commit “Bombs,” Please</h4><p>On occasion, you will find that you are spending a significant amount of
time working with someone else’s code. To avoid potentially painful
merges, please (1) inform the author when you create the branch and (2)
set the mail hook so that git sends a commit message to both you and the
original author. Furthermore, you should test your changes on the actual
code base. In some cases it is acceptable to delay such tests, e.g., when
you will not know for a long time whether the performance implication
allow a commit to the PLT repository.</p><p><span class="refelem"><span class="refcolumn"><span class="refcontent">See
<a href="http://git.racket-lang.org/intro.html">the write-up</a> on
using git in PLT for details.</span></span></span></p><p><div class="SIntrapara">As a reminder, here are the essential elements of git for working on a
fork:
</div><div class="SIntrapara"><ul><li><p><div class="SIntrapara">setup a fork:
</div><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">ssh pltgit fork plt eli/my-plt</span></p></td></tr></table></div></p></li><li><p><div class="SIntrapara">setup mail notifications:
</div><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">ssh pltgit config set eli/my-plt hooks.counter true</span></p></td></tr><tr><td><p><span class="stt">ssh pltgit config set eli/my-plt hooks.mailinglist eli@barzilay.org,...</span></p></td></tr></table></div></p></li><li><p><div class="SIntrapara">allow someone else to push commits to my repository:
</div><div class="SIntrapara"><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">ssh pltgit setperms eli/my-plt</span></p></td></tr><tr><td><p><span class="stt">RW eli</span></p></td></tr><tr><td><p><span class="stt">RW someone-else</span></p></td></tr><tr><td><p><span class="stt">^D</span></p></td></tr></table></div></p></li></ul></div></p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="Language_and_Performance.html" title="backward to "6 Language and Performance"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "How to Program Racket"" data-pltdoc="x">up</a> <a href="Acknowledgment.html" title="forward to "8 Acknowledgment"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|