@ciao-lang/ts-ciao-interface
Version:
Simple Ciao interface for node.
19 lines • 16.2 kB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Code Reviews — </title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton"><span id="sidebar-button-arrow">☰</span></a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-grimoire-128h_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><span class="lpdoc-on-right"><a class="lpdoc-navbutton" href="CiaoDevel.html">↑</a><a class="lpdoc-navbutton" href="TestChanges.html">←</a><a class="lpdoc-navbutton" href="NewRelease.html">→</a><a class="lpdoc-navbutton" href="CiaoDevelsearch.html">🔍</a></span><span><a href="CiaoDevelfulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="CiaoDevel.html">CiaoDevel Reference Manual</a> »<br/> </li><li><a href=""><strong>Code Reviews</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#How to Submit Code for Review">How to Submit Code for Review</a></li><ul><li><a href="#Step 1: Prepare your working directory">Step 1: Prepare your working directory</a></li><li><a href="#Step 2: Create a local branch you will be working on">Step 2: Create a local branch you will be working on</a></li><li><a href="#Step 3: Create a code revision (AKA a Diff)">Step 3: Create a code revision (AKA a <span class="lpdoc-var">Diff</span>)</a></li><ul><li><a href="#Revisions associated with a specific task">Revisions associated with a specific task</a></li><li><a href="#Revisions with no task">Revisions with no task</a></li></ul><li><a href="#Step 4: Respond to Reviews or Update a Revision">Step 4: Respond to Reviews or Update a Revision</a></li><li><a href="#Step 5: Landing Changes">Step 5: Landing Changes</a></li></ul><li><a href="#How to Review Code">How to Review Code</a></li><ul><li><a href="#Pre-commit reviews with Differential">Pre-commit reviews with Differential</a></li><ul><li><a href="#Checking out the Phabricator branch (e.g., D24) with the changes">Checking out the Phabricator branch (e.g., D24) with the changes</a></li><li><a href="#Suggesting modifications">Suggesting modifications</a></li><li><a href="#Updating the branch after changes">Updating the branch after changes</a></li><li><a href="#Accepting Changes">Accepting Changes</a></li></ul><li><a href="#Post-commit reviews with Audit">Post-commit reviews with Audit</a></li></ul><li><a href="#Some Useful arcanist Commands">Some Useful <tt>arcanist</tt> Commands</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Code Reviews</h1><a class="lpdoc-idx-anchor" href="CiaoDevelsearch.html#CodeReviews"></a>
<strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="The Ciao Development Team" href="CiaoDevelsearch.html#The Ciao Development Team">The Ciao Development Team</a>.<p>
This describes the Ciao code review workflow using <strong>Phabricator</strong> and <strong>Arcanist</strong>.<p><div id="How to Submit Code for Review"><h2>How to Submit Code for Review</h2> <div id="Step 1: Prepare your working directory"><h3>Step 1: Prepare your working directory</h3> By default Arcanist assumes the <em>One Idea, One Commit</em> approach for each task. In practice this means that your working directory should not contain any local changes with respect to the <span class="lpdoc-var">HEAD</span> commit when you start working on a new task. Should you have any changes you would like to keep, use '<tt>git stash:</tt>'<p><pre class="lpdoc-codeblock">[git stash] <span class="comment-delimiter"># </span><span class="comment">optional step, only if you have changes to tracked files
</span>git checkout master
git pull origin master</pre> </div><div id="Step 2: Create a local branch you will be working on"><h3>Step 2: Create a local branch you will be working on</h3> To begin, prepare your working directory by creating a branch with the name of the task that you will be working on. Assuming that your default branch is '<tt>master</tt>' and the task is T42, do:<p><pre class="lpdoc-codeblock">arc branch T42 <span class="comment-delimiter"># </span><span class="comment">alternatively: arc feature T42</span></pre>The '<tt>arc branch</tt>' command creates a local git task branch and switches to it. You should name your task branch the same as the Task you are working on. If you do so, Arcanist will automatically link your Diff and the Task together.<p><div class="lpdoc-alert"> <strong>Working with multiple branches:</strong> the task branches are set up to track the local branch you are currently working on. If you accidentally create a task branch from a wrong local branch, simply delete the task branch with '<tt>git branch -d ...</tt>', check out the correct local branch and repeat the '<tt>arc branch</tt>' command. It also seems to be possible in some cases to <a href="https://stackoverflow.com/q/23920380">change the local branch manually</a> or <a href="https://stackoverflow.com/q/19819252">'<tt>arc diff</tt>' against a particular local branch</a>. </div> <p></div><div id="Step 3: Create a code revision (AKA a Diff)"><h3>Step 3: Create a code revision (AKA a <span class="lpdoc-var">Diff</span>)</h3> <div id="Revisions associated with a specific task"><h4>Revisions associated with a specific task</h4> This is the default workflow.<p>After you finish working on the task on the Task branch, you commit the changes and start a code review:<p><pre class="lpdoc-codeblock">git commit -a <span class="string">"commit message"</span>
<span class="comment-delimiter"># </span><span class="comment">or add the files individually and commit them as:
</span><span class="comment-delimiter"># </span><span class="comment">git add FILE(s)
</span><span class="comment-delimiter"># </span><span class="comment">git commit -m "commit message"
</span>arc diff</pre>The commit message should be a one-liner (preferable no more than 80 characters) summarizing the changes. It must begin with a tag that specifies which part of the system was changed (e.g. (tests), (core), (rtchecks), fix(lpdoc), etc.).<p>The '<tt>arc diff</tt>' command will open a text editor (provided in the <span class="lpdoc-var">EDITOR</span> environment variable) with an extended commit message template. The first line(s) should correspond to the one-liner summary entered earlier. Fill the rest of the lines with the detailed information about the changes.<p>The <span class="lpdoc-var">Summary</span> and <span class="lpdoc-var">Test</span> fields are mandatory for filling (in some cases <tt>N/A</tt> can be put into <span class="lpdoc-var">Test</span> field iff the changes do not affect any executable code). The <span class="lpdoc-var">Summary</span> should include a more detailed explanation in several sentences or bullet points about the new changes/fixes in the Diff. The rest of the fields (<span class="lpdoc-var">Reviewers</span>, <span class="lpdoc-var">Subscribers</span>, <span class="lpdoc-var">Projects</span>) can be filled later through the web interface.<p>When you save the commit message in the editor and exit it, Arcanist submits the changes to the Phabricator server for review and updates your local commit to include the URL of the revision on the server.<p><div class="lpdoc-alert"> <strong>Note</strong>: the detailed message entered at this point will be used also in the web interface of Phabricator. You can manually introduce changes to it there (e.g., add/remove reviewers, associate projects, edit/update the text, etc.). This version will also be used when you commit your final changes to the <tt>master</tt> branch, so do not worry if you entered something wrong. Just make sure that the commit message in the web interface is the one you want before the final commit. </div> <p></div><div id="Revisions with no task"><h4>Revisions with no task</h4> In some exceptional cases (e.g., for isolated changes related to a very specific task when there has been some previous agreement on the changes) it is acceptable to create a code revision without associating it to a specific task. However, to avoid complications during landing changes ('<tt>arc land</tt>') all the new changes should be implemented on a local branch, NOT on <tt>master</tt>. The workflow does not differ significantly for the developer and is the same for the reviewer.<p>To create such revision it is enough to execute the '<tt>git commit</tt>' and '<tt>arc diff</tt>' commands.<p>To close such revision it is enough to execute the '<tt>arc amend</tt>' (or '<tt>arc close-revision</tt>') and '<tt>git push</tt>' commands.<p></div></div><div id="Step 4: Respond to Reviews or Update a Revision"><h3>Step 4: Respond to Reviews or Update a Revision</h3> If a reviewer requests changes to the revision and you agree with those, implement them and submit a new code revision. To do this you introduce the changes as a new commit:<p><pre class="lpdoc-codeblock">git commit -m <span class="string">"new changes description"</span>
arc diff</pre>Arcanist will send new changes back to the server for another round of review.<p>At the point of committing the final changes (see '<tt>arc land</tt>' below), all commits in the differential revision will be flattened to just one commit with all the changes. The messages entered at this point are mostly for self-orientation, and the developer can go back easily to previous states of the local branch with the traditional '<tt>git checkout</tt>' commands. See also the documentation for the '<tt>arc diff --plan-changes</tt>' option below.<p><div class="lpdoc-alert"> <strong>Note:</strong> make sure you never merge anything from the master branch (or other branches) onto your local branch while you are working on it. The SHA of the last commit on your local branch should not change until you '<tt>arc land</tt>' changes. </div> <p>If you had to roll back your commit before submitting an updated Diff and <tt>arc</tt> lost the track of it, you can still associate it with the specific revision with:<p><pre class="lpdoc-codeblock">arc diff --update <revision></pre>Alternatively, a brand new revision can be created with:<p><pre class="lpdoc-codeblock">arc diff --create</pre> </div><div id="Step 5: Landing Changes"><h3>Step 5: Landing Changes</h3> Once a reviewer requests no more modifications, the changes should be pushed to the repository with:<p><pre class="lpdoc-codeblock">arc land</pre>If no conflicts occur Arcanist merges the changes into master, deletes the local working branch, and pushes the changes to origin. Note that <tt>arc land</tt> can be executed for a Diff that was not accepted by any reviewer, but it is not advised to do so.<p>If conflicts occur, in most cases they are caused by unsuccessful merging of the commits that happened while you were working on the task. In most cases it should suffice to do the following:<p><pre class="lpdoc-codeblock"><span class="comment-delimiter"># </span><span class="comment">fix conflicts
</span>git commit
arc land</pre>If this does not work, a rebase can be performed before landing:<p><pre class="lpdoc-codeblock">git merge --abort
git fetch
git rebase -i origin/master
<span class="comment-delimiter"># </span><span class="comment">... fix merge conflicts
</span>git add
git rebase --continue
<span class="comment-delimiter"># </span><span class="comment">... fix more conflicts should they occur, until the code is synced
</span>arc land</pre> </div></div><div id="How to Review Code"><h2>How to Review Code</h2> The goal of the code reviewer is to identify:<p><ul> <li>Weird coding styles. <li>Code in intermediate state (unless absolutely necessary). <li>Non-English comments, identifiers, strings (unless absolutely necessary). <li>Missing <span class="lpdoc-var">NODISTRIBUTE</span>, <span class="lpdoc-var">NOCOMPILE</span> in directories that are not ready for distribution. <li>Failure in automated tests. </ul> The following subsections describe the code reviewing actions with the Phabricator web interface and the Archanist commands.<p><div id="Pre-commit reviews with Differential"><h3>Pre-commit reviews with Differential</h3> <div id="Checking out the Phabricator branch (e.g., D24) with the changes"><h4>Checking out the Phabricator branch (e.g., D24) with the changes</h4> To try the new changes:<p><ul> <li>Do '<tt>git checkout</tt>' to the Diff point (or '<tt>git checkout master</tt>' if you have most of the recent commits), and <li>create a local branch with '<tt>arc patch D24,</tt>' <li>compile, test, ... </ul> (This branch can be deleted later with '<tt>git branch -D arcpatch-D24</tt>'.)<p></div><div id="Suggesting modifications"><h4>Suggesting modifications</h4> <ul> <li>To annotate the changes with inline comments got to Phabricator and perform <em>click and drag</em> on the respective line numbers. <li>To request changes fill the text area at the bottom of the page in Phabricator with instructions or extended comments, select <em>Request Changes</em> action from the drop-down list and hit the <em>Submit</em> button. </ul> </div><div id="Updating the branch after changes"><h4>Updating the branch after changes</h4> One cannot really update the branch with the patch: instead for each new update of a Diff the old patch branch should be deleted, and a fresh one created from the <tt>master</tt> branch, i.e.:<p><ul> <li>Switch to master with '<tt>git checkout master</tt>'. <li>Delete the (now outdated) branch with '<tt>git branch -D arcpatch-D24</tt>'. <li>Check out the branch again (which now will contain the updates): '<tt>arc patch D24</tt>'. </ul> Repeat the actions above until the changes look good.<p></div><div id="Accepting Changes"><h4>Accepting Changes</h4> To accept changes select in Phabricator the <em>Accept Revision</em> action from the drop-down list and hit the <em>Submit</em> button.<p></div></div><div id="Post-commit reviews with Audit"><h3>Post-commit reviews with Audit</h3> For the commits that were pushed/landed without prior review it is still possible to make a code review through Phabricator's web interface:<p><ul> <li>from the main page navigate to the <span class="lpdoc-var">Audit</span> section in the tools list; <li>select the commit of interest, review it, annotate it with comments if needed; <li>in the <em>Add Action...</em> menu at the bottom of the web page either <em>Accept Commit</em> or <em>Raise Concern</em>. </ul> </div></div><div id="Some Useful arcanist Commands"><h2>Some Useful <tt>arcanist</tt> Commands</h2> <div class="lpdoc-alert"> <strong>Note</strong>: invocations of the <tt>arc</tt> utility require a working Internet connection. </div> <p><ul> <li>'<tt>arc feature</tt>': Lists the available branches and their revision status (like <tt>git branch</tt> but adding extra information). <li>'<tt>arc diff --plan-changes</tt>': Updated the current Diff but does not request a review from its reviewers, useful for incomplete temporal saves (e.g., daily saves). </ul> Also, <tt>arc</tt> understands some keywords in commit messages (see <a href="https://secure.phabricator.com/T5132">this web page</a> for details):<p><ul> <li>attach a revision or a commit to a task with <tt>Ref T42</tt> in the summary/commit message; <li>close a task when pushing a commit with <tt>Fixes T42</tt> in the summary/commit message; </ul> These commands also work for regular commits (e.g., pushed via <tt>git push</tt>, not only during <tt>arc land</tt>).</div><br/></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>