456713829f79
hg-review: Update documentation.
| author | Steve Losh <steve@stevelosh.com> |
|---|---|
| date | Tue, 15 Jun 2010 00:21:13 -0400 |
| parents | 08c786bf864c |
| children | 75e16ecaa86d |
| branches/tags | (none) |
| files | hg-review/_sources/concepts.txt hg-review/concepts.html hg-review/index.html hg-review/searchindex.js |
Changes
--- a/hg-review/_sources/concepts.txt Mon Jun 14 23:35:03 2010 -0400 +++ b/hg-review/_sources/concepts.txt Tue Jun 15 00:21:13 2010 -0400 @@ -31,8 +31,118 @@ Other Code Review Tools ----------------------- +There are a lot of "code review tools" out there. + +The primary author of hg-review has a lot of experience with `Atlassian +Crucible <http://www.atlassian.com/software/crucible/>`_, but some other +popular tools include: + +* `Rietveld <http://codereview.appspot.com/>`_ +* `Reviewboard <http://www.reviewboard.org/>`_ +* `Gerrit <http://code.google.com/p/gerrit/>`_ +* `Code Collaborator <http://smartbear.com/codecollab.php>`_ + +All of these tools try to accomplish the same goal: making it easy for +developers to tell each other how to write better code. + +hg-review has the same goal, but it goes about it a little differently. + Distributed Code Review ----------------------- +Let's back up for just a second and talk about version control. Some of the +most popular version control systems a few years ago were *centralized* systems +like `Subversion <http://subversion.apache.org/>`_ and +`CVS <http://www.nongnu.org/cvs/>`_. + +With these systems you had a central server that contained all the history of +your project. You would push changes to this central server and it would store +them. + +In the past half-decade or so there has been a move toward *decentralized* or +*distrubuted* version control systems. With these systems you commit to your +local machine and then *push* and *pull* your commits to other people. + +Code review tools, however, seem to have remained rooted in the "centralized +server" approach. Even the tools that support decentralized version control +systems like `git <http://git-scm.com>`_ and `Mercurial <http://hg-scm.org>`_ +rely on a central server to store the code review data. + +hg-review does away with the "centralized data store" model and embraces +Mercurial's distributed nature. Code review data is held in a normal Mercurial +repository and can be pushed and pulled like any other type of data. + +This has several advantages, the biggest one being that you can review code +while offline (while in a bus, plane, train or car, or example) without +sacrificing any functionality. + +It also means that the full power of Mercurial, such as tracking history and +signing changesets with GPG, can be brought to bear on the review data. + +Review Data +----------- + +hg-review tracks two kinds of code review data: comments and signoffs. + +Comments are simple comments that people make about changesets. People can +comment on: + +* A changeset as a whole. +* A specific file within a changeset. +* One or more lines of a specific file within a changeset. + +Signoffs, on the other hand, *always* apply to a changeset as a whole. Each +person can have on signoff for any particular changeset (though they can edit +their signoff later). + +Signoffs can be used for whatever purpose your project might find useful, but +the author of hg-review recommends that they be used to mean: + + I approve of this changeset and think it should make its way to production. + +for signoffs of "Yes" and: + + I do not approve of this changeset and do not think it should make its way to + production without another changeset on top of it that fixes the problems + I have listed. + +for signoffs of "No." + +Signoffs of "neutral" might mean: + + This changeset doesn't really impact me, so I don't care. + +or: + + I've looked at this code but don't have the expertise to provide a useful + opinion. + + Repository Structure -------------------- + +While it's not necessary to know exactly how the guts of hg-review work, it +*is* helpful to understand the basic idea behind it. + +Let's say you have a project with a Mercurial repository in +``~/src/yourproject/`` and you'd like to start using hg-review with it. + +The first thing to understand is that Mercurial itself stores data about this +local repository in ``~/src/yourproject/.hg/``, and that data is local to your +machine. It is never committed or tracked by Mercurial, but is instead used by +the Mercurial program itself to work with your repository. + +hg-review creates a *separate* Mercurial repository to keep track of its data. +It stores this repository in ``~/src/yourproject/.hg/review/``. + +Because this is inside of Mercurial's internal ``.hg`` directory of your +project, changes to the review data (like comments and signoffs) won't be +tracked by your project's repository. + +Instead, hg-review manages its own data in its own repository to avoid +cluttering up your project's log with useless "added a comment"-type commits. + +This structure means that you can ``cd`` into the review data repository itself +and interact with it just as you would a normal Mercurial repository. You can +``push`` and ``pull`` to and from other people, backout changesets, and do +anything else you could with a normal Mercurial repository.
--- a/hg-review/concepts.html Mon Jun 14 23:35:03 2010 -0400 +++ b/hg-review/concepts.html Tue Jun 15 00:21:13 2010 -0400 @@ -68,12 +68,97 @@ </div> <div class="section" id="other-code-review-tools"> <h2>Other Code Review Tools<a class="headerlink" href="#other-code-review-tools" title="Permalink to this headline">¶</a></h2> +<p>There are a lot of “code review tools” out there.</p> +<p>The primary author of hg-review has a lot of experience with <a class="reference external" href="http://www.atlassian.com/software/crucible/">Atlassian +Crucible</a>, but some other +popular tools include:</p> +<ul class="simple"> +<li><a class="reference external" href="http://codereview.appspot.com/">Rietveld</a></li> +<li><a class="reference external" href="http://www.reviewboard.org/">Reviewboard</a></li> +<li><a class="reference external" href="http://code.google.com/p/gerrit/">Gerrit</a></li> +<li><a class="reference external" href="http://smartbear.com/codecollab.php">Code Collaborator</a></li> +</ul> +<p>All of these tools try to accomplish the same goal: making it easy for +developers to tell each other how to write better code.</p> +<p>hg-review has the same goal, but it goes about it a little differently.</p> </div> <div class="section" id="distributed-code-review"> <h2>Distributed Code Review<a class="headerlink" href="#distributed-code-review" title="Permalink to this headline">¶</a></h2> +<p>Let’s back up for just a second and talk about version control. Some of the +most popular version control systems a few years ago were <em>centralized</em> systems +like <a class="reference external" href="http://subversion.apache.org/">Subversion</a> and +<a class="reference external" href="http://www.nongnu.org/cvs/">CVS</a>.</p> +<p>With these systems you had a central server that contained all the history of +your project. You would push changes to this central server and it would store +them.</p> +<p>In the past half-decade or so there has been a move toward <em>decentralized</em> or +<em>distrubuted</em> version control systems. With these systems you commit to your +local machine and then <em>push</em> and <em>pull</em> your commits to other people.</p> +<p>Code review tools, however, seem to have remained rooted in the “centralized +server” approach. Even the tools that support decentralized version control +systems like <a class="reference external" href="http://git-scm.com">git</a> and <a class="reference external" href="http://hg-scm.org">Mercurial</a> +rely on a central server to store the code review data.</p> +<p>hg-review does away with the “centralized data store” model and embraces +Mercurial’s distributed nature. Code review data is held in a normal Mercurial +repository and can be pushed and pulled like any other type of data.</p> +<p>This has several advantages, the biggest one being that you can review code +while offline (while in a bus, plane, train or car, or example) without +sacrificing any functionality.</p> +<p>It also means that the full power of Mercurial, such as tracking history and +signing changesets with GPG, can be brought to bear on the review data.</p> +</div> +<div class="section" id="review-data"> +<h2>Review Data<a class="headerlink" href="#review-data" title="Permalink to this headline">¶</a></h2> +<p>hg-review tracks two kinds of code review data: comments and signoffs.</p> +<p>Comments are simple comments that people make about changesets. People can +comment on:</p> +<ul class="simple"> +<li>A changeset as a whole.</li> +<li>A specific file within a changeset.</li> +<li>One or more lines of a specific file within a changeset.</li> +</ul> +<p>Signoffs, on the other hand, <em>always</em> apply to a changeset as a whole. Each +person can have on signoff for any particular changeset (though they can edit +their signoff later).</p> +<p>Signoffs can be used for whatever purpose your project might find useful, but +the author of hg-review recommends that they be used to mean:</p> +<blockquote> +I approve of this changeset and think it should make its way to production.</blockquote> +<p>for signoffs of “Yes” and:</p> +<blockquote> +I do not approve of this changeset and do not think it should make its way to +production without another changeset on top of it that fixes the problems +I have listed.</blockquote> +<p>for signoffs of “No.”</p> +<p>Signoffs of “neutral” might mean:</p> +<blockquote> +This changeset doesn’t really impact me, so I don’t care.</blockquote> +<p>or:</p> +<blockquote> +I’ve looked at this code but don’t have the expertise to provide a useful +opinion.</blockquote> </div> <div class="section" id="repository-structure"> <h2>Repository Structure<a class="headerlink" href="#repository-structure" title="Permalink to this headline">¶</a></h2> +<p>While it’s not necessary to know exactly how the guts of hg-review work, it +<em>is</em> helpful to understand the basic idea behind it.</p> +<p>Let’s say you have a project with a Mercurial repository in +<tt class="docutils literal"><span class="pre">~/src/yourproject/</span></tt> and you’d like to start using hg-review with it.</p> +<p>The first thing to understand is that Mercurial itself stores data about this +local repository in <tt class="docutils literal"><span class="pre">~/src/yourproject/.hg/</span></tt>, and that data is local to your +machine. It is never committed or tracked by Mercurial, but is instead used by +the Mercurial program itself to work with your repository.</p> +<p>hg-review creates a <em>separate</em> Mercurial repository to keep track of its data. +It stores this repository in <tt class="docutils literal"><span class="pre">~/src/yourproject/.hg/review/</span></tt>.</p> +<p>Because this is inside of Mercurial’s internal <tt class="docutils literal"><span class="pre">.hg</span></tt> directory of your +project, changes to the review data (like comments and signoffs) won’t be +tracked by your project’s repository.</p> +<p>Instead, hg-review manages its own data in its own repository to avoid +cluttering up your project’s log with useless “added a comment”-type commits.</p> +<p>This structure means that you can <tt class="docutils literal"><span class="pre">cd</span></tt> into the review data repository itself +and interact with it just as you would a normal Mercurial repository. You can +<tt class="docutils literal"><span class="pre">push</span></tt> and <tt class="docutils literal"><span class="pre">pull</span></tt> to and from other people, backout changesets, and do +anything else you could with a normal Mercurial repository.</p> </div> </div> @@ -89,6 +174,7 @@ <li><a class="reference external" href="#code-review-basics">Code Review Basics</a></li> <li><a class="reference external" href="#other-code-review-tools">Other Code Review Tools</a></li> <li><a class="reference external" href="#distributed-code-review">Distributed Code Review</a></li> +<li><a class="reference external" href="#review-data">Review Data</a></li> <li><a class="reference external" href="#repository-structure">Repository Structure</a></li> </ul> </li>
--- a/hg-review/index.html Mon Jun 14 23:35:03 2010 -0400 +++ b/hg-review/index.html Tue Jun 15 00:21:13 2010 -0400 @@ -84,6 +84,7 @@ <li class="toctree-l2"><a class="reference external" href="concepts.html#code-review-basics">Code Review Basics</a></li> <li class="toctree-l2"><a class="reference external" href="concepts.html#other-code-review-tools">Other Code Review Tools</a></li> <li class="toctree-l2"><a class="reference external" href="concepts.html#distributed-code-review">Distributed Code Review</a></li> +<li class="toctree-l2"><a class="reference external" href="concepts.html#review-data">Review Data</a></li> <li class="toctree-l2"><a class="reference external" href="concepts.html#repository-structure">Repository Structure</a></li> </ul> </li>
--- a/hg-review/searchindex.js Mon Jun 14 23:35:03 2010 -0400 +++ b/hg-review/searchindex.js Tue Jun 15 00:21:13 2010 -0400 @@ -1,1 +1,1 @@ -Search.setIndex({desctypes:{},terms:{changeset:2,all:2,code:[0,5,2],signoff:[0,1],just:[2,5],over:2,becaus:5,concept:[0,5,2],file:[0,3,2],hack:[0,6],hate:[],find:5,help:5,perfect:5,web:[0,4,1,2],onli:[2,5],locat:2,easi:5,also:[2,5],flask:2,fix:5,should:2,solitari:[],init:[0,2],onc:2,anyon:2,local:[0,4,2],easier:5,applic:0,them:2,sourc:2,around:[0,5],thei:5,format:[0,3],python:[0,3,2],initi:[0,2],repo:2,jinja2:2,know:[0,5,2],got:0,report:[0,2],now:[0,2],requir:2,enabl:0,choic:0,disturb:[],experi:5,somewher:[0,2],like:[2,5],anyth:0,did:5,changelog:2,server:[0,4],remot:[2,5],api:[0,3],integr:0,each:5,quick:2,page:[],wrote:5,depend:2,pleas:2,encount:2,set:[2,5],often:5,some:0,realli:2,see:2,our:5,out:0,index:[],what:[0,4],poke:0,someth:2,definit:5,content:[],version:2,simplest:5,"new":2,awai:[0,5],hgreview:2,localhost:[0,2],creatur:[],run:2,clutter:2,learn:0,usag:[0,2],here:0,extens:[0,2],host:2,let:2,repositori:[0,5,3,2],ask:5,layout:[0,6],post:2,care:5,both:2,search:[],wai:2,befor:5,could:5,wrong:5,unfortun:5,thing:2,tour:2,place:0,isn:5,sjl:[0,2],commit:2,chanc:5,first:[0,2],comment:[0,1],own:0,simpli:5,overview:[0,2],modul:[],period:5,down:2,alreadi:[0,2],done:2,url:2,path:[0,2],instal:[0,2],guid:0,open:[0,2],your:[0,5,2],coupl:2,start:[0,2],visit:2,add:[0,2],next:2,mercuri:[0,2],few:2,interfac:[0,4,1,2],easiest:2,basic:[0,5],hei:5,friend:5,more:[0,5],luckili:0,org:[0,2],form:5,especi:5,fire:2,peopl:5,thousand:5,about:2,yourproject:[],worri:2,review:[0,1,2,4,5,6],"catch":5,line:[0,1,2],hold:2,impati:0,than:[0,5],pull:2,look:5,possibl:5,provid:1,might:[2,5],work:[2,5],second:5,structur:[0,5],tell:5,project:2,matter:2,"while":2,mile:5,can:[2,5],error:[2,5],exist:[2,5],problem:[2,5],document:[0,6,2],browser:[0,2],sai:5,quickstart:0,creat:2,readi:[0,2],ani:2,indic:[],itself:0,right:0,have:[2,5],tabl:[],need:[0,5,2],seen:5,check:[0,1,2],greater:5,alwai:5,develop:[0,5],welcom:[],want:[0,2],turn:5,perform:0,suggest:2,make:[2,5],get:2,when:[0,5],access:2,write:5,how:2,other:[0,5,2],read:[2,5],take:5,test:[0,6],you:[0,5,4,2],probabl:[2,4],simpl:0,bundl:2,sure:2,http:[0,2],distribut:[0,5],deploy:[0,4],clone:[0,2],time:2,tool:[0,5],someon:5,most:[4,5],plai:0,user:[0,5],data:[0,3,2],goal:5,bitbucket:[0,2],don:2,practic:5,bug:[0,2],directori:[0,2],later:2,well:2,without:2,person:5,anoth:5,exampl:2,command:[0,1,2],thi:[0,5,2],titl:[],programm:[],hgrc:[0,2],usual:[]},titles:["hg-review documentation","Command Line Interface","Overview","API","Web Interface","Concepts","Hacking hg-review"],modules:{},descrefs:{},filenames:["index","cli","overview","dev","webui","concepts","hacking"]}) \ No newline at end of file +Search.setIndex({desctypes:{},terms:{all:[2,5],concept:[0,5,2],mile:5,hate:[],depend:2,flask:2,init:[0,2],program:5,sourc:2,offlin:5,disturb:[],did:5,list:5,"try":5,gut:5,quick:2,pleas:2,natur:5,sign:5,past:5,second:5,even:5,index:[],what:[0,4],poke:0,access:2,version:[2,5],"new":2,hgreview:2,whatev:5,full:5,never:5,here:0,let:[2,5],layout:[0,6],search:[],sjl:[0,2],opinion:5,chang:5,chanc:5,backout:5,appli:5,modul:[],brought:5,api:[0,3],instal:[0,2],from:5,would:5,visit:2,two:5,next:2,few:[2,5],recommend:5,decentr:5,type:5,tell:5,more:[0,5],peopl:5,train:5,particular:5,hold:2,easiest:2,car:5,work:[2,5],histori:5,remain:5,can:[2,5],learn:0,purpos:5,root:5,control:5,distrubut:5,quickstart:0,indic:[],want:[0,2],unfortun:5,alwai:5,goal:5,thing:[2,5],anoth:5,write:5,how:[2,5],anyon:2,instead:5,simpl:[0,5],product:5,clone:[0,2],befor:5,wrong:5,plane:5,embrac:5,data:[0,5,3,2],practic:5,talk:5,help:5,over:2,move:5,approv:5,becaus:5,top:5,held:5,perfect:5,fix:5,better:5,solitari:[],decad:5,might:[2,5],easier:5,them:[2,5],greater:5,thei:5,python:[0,3,2],initi:[0,2],jinja2:2,half:5,now:[0,2],choic:0,somewher:[0,2],anyth:[0,5],edit:5,gerrit:5,separ:5,each:5,mean:5,idea:5,realli:[2,5],year:5,our:5,out:[0,5],accomplish:5,goe:5,content:[],got:0,insid:5,ask:5,org:[0,2],care:5,could:5,keep:5,turn:5,place:0,isn:5,think:5,first:[0,5,2],onc:2,alreadi:[0,2],done:2,open:[0,2],primari:5,ont:[],differ:5,interact:5,gpg:5,system:5,mercuri:[0,5,2],store:5,luckili:0,especi:5,tool:[0,5],review:[0,1,2,4,5,6],exactli:5,than:[0,5],kind:5,remot:[2,5],structur:[0,5],project:[2,5],matter:2,friend:5,were:5,toward:5,browser:[0,2],sai:5,ani:[2,5],have:[2,5],tabl:[],need:[0,5,2],seen:5,seem:5,also:[2,5],exampl:[2,5],useless:5,sure:2,distribut:[0,5],deploy:[0,4],track:5,most:[4,5],plai:0,don:[2,5],url:2,later:[2,5],doe:5,someth:2,changeset:[2,5],signoff:[0,1,5],hack:[0,6],find:5,impact:5,onli:[2,5],locat:2,should:[2,5],local:[0,5,4,2],get:2,bear:5,repo:2,report:[0,2],requir:2,enabl:0,provid:[1,5],integr:0,contain:5,wrote:5,set:[2,5],see:2,expertis:5,hgrc:[0,2],behind:5,won:5,simplest:5,awai:[0,5],experi:5,approach:5,extens:[0,2],both:2,howev:5,tour:2,whole:5,comment:[0,1,5],simpli:5,overview:[0,2],period:5,path:[0,2],guid:0,reviewboard:5,code:[0,5,2],coupl:2,been:5,basic:[0,5],oth:[],fire:2,thousand:5,atlassian:5,understand:5,"catch":5,impati:0,crucibl:5,look:5,"while":[2,5],error:[2,5],advantag:5,readi:[0,2],worri:2,itself:[0,5],clutter:[2,5],sever:5,develop:[0,5],welcom:[],author:5,perform:0,suggest:2,make:[2,5],same:5,document:[0,6,2],http:[0,2],someon:5,hand:5,user:[0,5],well:2,person:5,without:[2,5],command:[0,1,2],thi:[0,5,2],programm:[],model:5,usual:[],just:[2,5],collabor:5,web:[0,4,1,2],easi:5,had:5,littl:5,add:[0,2],els:5,take:5,applic:0,around:[0,5],format:[0,3],read:[2,5],know:[0,5,2],like:[2,5],specif:5,changelog:2,server:[0,4,5],necessari:5,popular:5,page:[],encount:2,right:0,often:5,some:[0,5],back:5,intern:5,home:[],avoid:5,though:5,definit:5,localhost:[0,2],machin:5,creatur:[],run:2,power:5,usag:[0,2],sacrif:5,host:2,repositori:[0,5,3,2],post:2,src:5,about:[2,5],central:5,manag:5,commit:[2,5],own:[0,5],within:5,down:2,subvers:5,your:[0,5,2],git:5,lof:[],log:5,wai:[2,5],support:5,start:[0,5,2],reli:5,interfac:[0,4,1,2],includ:5,lot:5,biggest:5,hei:5,"function":5,form:5,bundl:2,neutral:5,yourproject:5,line:[0,5,1,2],bug:[0,2],pull:[2,5],rietveld:5,possibl:5,problem:[2,5],creat:[2,5],doesn:5,exist:[2,5],file:[0,5,3,2],check:[0,1,2],probabl:[2,4],googl:[],titl:[],when:[0,5],other:[0,5,2],normal:5,test:[0,6],you:[0,5,4,2],meaning:[],ago:5,bitbucket:[0,2],directori:[0,5,2],time:2,push:5},titles:["hg-review documentation","Command Line Interface","Overview","API","Web Interface","Concepts","Hacking hg-review"],modules:{},descrefs:{},filenames:["index","cli","overview","dev","webui","concepts","hacking"]}) \ No newline at end of file