Commits

Patrick Mézard committed d2d132a

doc: update the README.text and commands documentation

Comments (0)

Files changed (2)

   http://golang.org/doc/contribute.html
 
 The fork reshapes the contribution workflow to better fit a regular Mercurial
-workflow, and notably to use changesets instead of local changes. A simple
-coding session looks like:
+workflow, and notably to use changesets instead of local changes. The extension
+brings the following commands:
 
-    $ ... write some changes ...
+* `clpush`: create or update a changelist from a Mercurial changeset
+* `clmail`: update a changelist from a changeset and send a notification email
+* `clclose`: close and optionally delete a changelist bound to a changeset
+* `climport`: turn a changelist into a regular local changeset
+
+See `hg help codereview` or `hg help COMMAND` for more details.
+
+A simple coding session looks like:
+
+    ... write some changes ...
+
     $ hg commit -m "some changes"
     $ hg clpush .
     Issue created. URL: https://codereview.appspot.com/123456
+    amending changeset changelist metadata
     
-    $ ... fix things on this changeset ...
+    ... fix things on this changeset ...
+
     $ hg commit --amend
     $ hg clpush .
     Issue updated. URL: https://codereview.appspot.com/123456
     
     $ hg clmail . 
     Issue updated. URL: https://codereview.appspot.com/123456
+    amending changeset changelist metadata
+
+    ... code is being reviewed and possibly accepted ...
+
+    $ hg clclose .
+    Issue deleted. URL: https://codereview.appspot.com/123456
+
+    ... and to import someone else work ...
+
+    $ hg climport 64740043
+    applying /temp/path/CL64740043XLUH_H.diff
+    CL 64740043 imported as:
+      19212:0e8f9e38c4f4 archive/tar: Added support for GNU sparse files.
+
+    $ hg parents
+    changeset:   19212:0e8f9e38c4f4
+    tag:         tip
+    parent:      19197:70499e5fbe5b
+    user:        david...@gmail.com
+    date:        Sun Feb 23 18:05:51 2014 +0100
+    summary:     archive/tar: Added support for GNU sparse files.
 
 Requirements and Setup
 ======================
 
         [extensions]
         codereview = /path/to/codereview/lib/codereview/codereview.py
-        [codereview]
-        ; Disable codereview precommit hook forbidding commit/rollback
-        allowediting = true
+
+How Does It Work?
+=================
+
+The main difference with the original extension is changelists are mapped to
+Mercurial changesets and changelist metadata is stored in changesets
+description as CLMETA- lines.
+
+`clpush`, `clmail` and `clclose` synchronizes local and remote data and
+metadata. `climport` creates regular changesets from remote changelists. Note
+they do not contain CLMETA- and are just normal changesets.
+
+Preparing changes for review is reduced to writing and rewriting changesets.
+Obviously the `evolve` extension can be used for that (see `amend`, `fold` and
+`uncommit` commands for instance), but any other tools like `histedit` or
+regular commands like `commit --amend` or `rebase` will do.
 
 Running the Tests
 =================
     $ cd /path/to/codereview
     $ (cd tests; /path/to/hg/tests/run-tests.py \
 	    --extra-config-opt=extensions.evolve=/path/to/evolve/evolve.py \
-	    test-codereview.t)
+	    test-clpush.t)
 
-Remarks
-=======
-
-Initially, I tried to preserve Go tree layout to ease backporting. But, while I
-have not broken previous features besides compatibility with oldish Mercurial,
-backporting can probably be ignored as the new features rely on `evolve` which
-is not even in Mercurial yet. Also, I am really trying to ease the contribution
-workflow, and committers commands getting in the way might just be removed.
-

lib/codereview/codereview.py

 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-'''Mercurial interface to codereview.appspot.com.
+"""Mercurial interface to codereview.appspot.com.
 
-To configure, set the following options in
-your repository's .hg/hgrc file.
+This extension requires evolve extension.
+
+To configure, set the following options in your repository's .hg/hgrc file.
 
 	[extensions]
 	codereview = /path/to/codereview.py
 
 The server should be running Rietveld; see http://code.google.com/p/rietveld/.
 
-In addition to the new commands, this extension introduces
-the file pattern syntax @nnnnnn, where nnnnnn is a change list
-number, to mean the files included in that change list, which
-must be associated with the current client.
+Rietveld changelists (CLs) are mapped to Mercurial changesets. 
 
-For example, if change 123456 contains the files x.go and y.go,
-"hg diff @123456" is equivalent to"hg diff x.go y.go".
+See :hg:`help clpush` to create or update changelists from local changesets.
 
-The extension registers a "clid" template keyword returning the changelist
-identifier of published changesets.
-'''
+See :hg:`help clmail` to update a changelist from a changeset and send a
+notification email.
+
+See :hg:`help clclose` to close and possibly delete a changelist.
+
+See :hg:`help climport` to turn changelists into regular local changesets.
+
+In addition to the new commands, this extension introduces the `clid` template
+keyword, returning the changelist identifier of a published changeset.
+"""
 
 import sys
 
 	This command requires evolve extension.
 
 	If selected changeset was clpushed before and contains CLMETA- lines in
-	it description, fetch metadata from remote changelist, merge them into
-	the local changelist, then update the remote changelist with local content.
+	its description, fetch metadata from remote changelist, merge them into
+	the local changelist and update the remote changelist with local content.
 
-	Otherwise, a new changelist is created on codereview server.
+	Otherwise, a new changelist is created on codereview server and CLMETA-
+	information is appended to the changeset description.
 
-	In both cases, the local changeset cannot be public if changelist metadata
-	is being created or updated.
+	In both cases, updating the description with CLMETA- lines requires the
+	changeset not to be public.
 	"""
 	if codereview_disabled:
 		raise hg_util.Abort(codereview_disabled)
 
 	This command requires evolve extension.
 
-	Uploads a patch to the code review server and then sends mail
-	to the reviewer and CC list asking for a review.
-
-	Since this can change changelist metadata, selected changeset may be
-	rewritten and cannot be public.
+	Uploads a patch to the code review server and sends mail to the
+	reviewer and CC list asking for a review. Updating metadata before
+	uploading changes can require the changeset to be rewritten, and
+	therefore be non-public.
 	"""
 	if codereview_disabled:
 		raise hg_util.Abort(codereview_disabled)
 def clclose(ui, repo, rev, **opts):
 	"""close a change list
 
-	Non-public changesets description is stripped of any changelist metadata.
+	Before being closed, a termination message is added to the changelist
+	linked to specified changeset.
+
+	With --delete the changelist is permanently deleted from code review
+	server.
+
+	If the local changeset is non-public, changelist metadata is removed from
+	its description. A warning is issued otherwise.
 	"""
 	if codereview_disabled:
 		raise hg_util.Abort(codereview_disabled)
 def climport(ui, repo, clname, **opts):
 	"""import a change list from code review server
 	
-	Retrieves the latest diff for specified changelist and import it on top
+	Retrieves the latest diff for specified changelist and imports it on top
 	of the current changeset. If the patch fails to apply, rejected hunks may
 	be left as .rej files in the working directory.
+
+	Because climport first applies changes to the working directory, climport
+	will abort if there are outstanding changes.
+
+	Imported changesets contain no metadata related to their source changelist.
+	Calling :hg:`clpush` on them creates new changelists.
 	"""
 	if codereview_disabled:
 		raise hg_util.Abort(codereview_disabled)
 def code_login(ui, repo, **opts):
 	"""log in to code review server
 
-	Logs in to the code review server, saving a cookie in
-	a file in your home directory.
+	Logs in to the code review server, saving a cookie in a file in your home
+	directory.
 	"""
 	if codereview_disabled:
 		raise hg_util.Abort(codereview_disabled)