# HG changeset patch # User Steve Losh # Date 1276575673 14400 # Node ID 456713829f79fd8325f847c1f177472d1e8b5123 # Parent 08c786bf864c958607ed1d811aec16cca946e295 hg-review: Update documentation. diff -r 08c786bf864c -r 456713829f79 hg-review/_sources/concepts.txt --- 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 `_, but some other +popular tools include: + +* `Rietveld `_ +* `Reviewboard `_ +* `Gerrit `_ +* `Code Collaborator `_ + +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 `_ and +`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 `_ and `Mercurial `_ +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. diff -r 08c786bf864c -r 456713829f79 hg-review/concepts.html --- 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 @@

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, but some other +popular tools include:

+ +

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 and +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 and Mercurial +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.

@@ -89,6 +174,7 @@
  • Code Review Basics
  • Other Code Review Tools
  • Distributed Code Review
    • +
  • Review Data
  • Repository Structure
    • diff -r 08c786bf864c -r 456713829f79 hg-review/index.html --- 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 @@
  • Code Review Basics
  • Other Code Review Tools
  • Distributed Code Review
    • +
  • Review Data
  • Repository Structure
    • diff -r 08c786bf864c -r 456713829f79 hg-review/searchindex.js --- 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