Subject: Re: [PATCH 2/2] Add a remote helper to interact with mediawiki (fetch & push)

From: Matthieu Moy <[email-masked]>
Date: Wed, 31 Aug 2011 13:54:04 +0200

Jonathan Nieder <[email-masked]> writes:

> Here's an old attempt to make the documentation a little easier to read,
> and hopefully also to add to.

Thanks, that helps. I wish we had all this earlier ;-).

> +Git sends the remote helper a list of commands on standard input, one
> +per line.  The first command is always the 'capabilities' command, 

Do we want to set this in stone? Wouldn't a Git implementation calling
"option" before "capabilities" be correct?

> +Capabilities
> +~~~~~~~~~~~~

(perhaps name the section "Overview of Capabilities"?)

[...]
> +'refspec' <refspec>::
> +	This modifies the 'import' capability, allowing the produced
> +	fast-import stream to modify refs in a private namespace
> +	instead of writing to refs/heads or refs/remotes directly.
> +	It is recommended that all importers providing the 'import'
> +	capability use this.
> ++
> +A helper advertising the capability
> +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}`
> +is saying that, when it is asked to `import refs/heads/topic`, the
> +stream it outputs will update the `refs/svn/origin/branches/topic`
> +ref.
> ++
> +This capability can be advertised multiple times.  The first
> +applicable refspec takes precedence.  The left-hand of refspecs
> +advertised with this capability must cover all refs reported by
> +the list command.  If no 'refspec' capability is advertised,
> +there is an implied `refspec {asterisk}:{asterisk}`.

Since this "Capabilities" section is meant to be an overview, I'd
shorten this to

+'refspec' <refspec>::
+	This modifies the 'import' capability, allowing the produced
+	fast-import stream to modify refs in a private namespace
+	instead of writing to refs/heads or refs/remotes directly.

and drop the detailed explanation here.

> +Capabilities for Fetching
> +~~~~~~~~~~~~~~~~~~~~~~~~~
[...]
> +'refspec' <refspec>::
> +	This modifies the 'import' capability.

Since this would be the "detailed explanation" part, this is the one
readers will read more carefully, so I'd put the recommandation right
here:

+	It is recommended that all importers providing the 'import'
+	capability use this.

and of course, keep this:

> ++
> +A helper advertising
> +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}`
> +in its capabilities is saying that, when it handles
> +`import refs/heads/topic`, the stream it outputs will update the
> +`refs/svn/origin/branches/topic` ref.
> ++
> +This capability can be advertised multiple times.  The first
> +applicable refspec takes precedence.  The left-hand of refspecs
> +advertised with this capability must cover all refs reported by
> +the list command.  If no 'refspec' capability is advertised,
> +there is an implied `refspec {asterisk}:{asterisk}`.
> +

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/