= Review-request Extension Idea =

Despite the fact Mercurial being advertised as Distributed, there is this aspect of all existing development having a central, or just official source repository.

This is just an idea I've got on my mind for quite sometime now, also encountered a [[http://stackoverflow.com/questions/7913168/plugin-pull-requests-for-mercurial|related question and answer]]:

  Q: Plugin with "pull-request" functionality for HG. Is there such plugin?<<BR>>
  <<BR>>A: Pull requests are inherently a repository hosting-platform specific function, it isn’t something that can be added to Mercurial as an extension. How would you imagine that it should work?

Following is what I imagine could be an extensible base for alternative approach to change contribution and the pull request model.  The main goal of this approach is to circumvent the need of a hosting platform like Bitbucket, or have an online repository to request a pull from at all.  It doesn't rule out hosting platforms and their integrated pull requests, but may be implemented by such platforms to enable even easier collaboration.

In general the suggested approach tries to provide an unified interface for couple of other approaches, including:

 * Mailing patches (using the [[PatchbombExtension|Patchbomb]] extension)
 * Posting changes to a Review Board server (using the [[ReviewboardExtension|Reviewboard]] extension)

So instead of requiring a "pull request" one would expose a "push request" facility to a repository.  "Push request" is probably not the best term, so may be "review (or change) request" would be more appropriate.  There are couple of distinct aspects I've thought about so far:

 * [[#Submission]] (from client)
 * [[#Management]] (on server)
 * [[#Access-control]]

== Submission ==

A new `request-review`, `post-review` or just `review` command would in general work just like push on the client-side – it will compute outgoing changes and push them to the server.  The difference will be the changes won't get immediately added to the history, but stored as separate bundle in a dedicated directory in the repository (like backup
bundles from `strip`, etc.).

One may think this all could be done by a regular push, and then have the server operating in a mode which doesn't immediately import the changes to the repo being served, but the `review` command might return additional information like new "review ID" created, and use that as additional argument for updating the same change request further.  The
`review` command may accept additional arguments like `--from` (email) and `--desc` (changegroup description), just like with Patchbomb.

This is probably all the client-side of the implementation needs.  No specific implementation as Patchbomb or Reviewboard - just this common interface which should already have pretty much everything implemented for over the wire protocol.

See the notes on [[#Access-control]] also.

== Management ==

Once the "change request" bundle is on the server, the owner or maintainer could review it whatever way it is convenient, including:

 * Having a hook which automatically posts the changes (à la Patchbomb) to an email address / mailing list
 * Having a hook which posts the changes to a Review Board server à la Reviewboard extension.  The extension iteself may provide such a hook, if this interface gets standardized
 * Expose read-only view of the request in hgweb à la Bitbucket/GitHub.  This may be extended by hosting platforms with full-blown discussion system.
 * Looking at the changes bundle up directly on the server

These are points which could be used to extend and provide more complete customized solutions to the general idea, but for proof of concept only the first one may be of interest for implementation part of this extension.  The Mercurial project may even try to employ it in practice.

After the repository owner has done reviewing the changes, he or she could:

 * Discard them / delete the review bundle;
 * Import the review bundle so it will become part of the upstream.

The difference with using just Patchbomb would be, the owner won't need to import patches from the mail but import the stored bundle directly.

=== Sample commands ===

So far I've assumed the review bundles will be stored in a directory under `.hg/`.  Having to look directly at this is probably not the nicest interface, so commands like:

 hg review --list::
 :: List submitted review requests.
 hg review --import <request_id>::
 :: Import the changes from the given review request (a la `hg unbundle`).
 hg review --delete <request_id>::
 :: Delete/discard the given review request.

could be provided.  These may be made remotely available to authorized owners, also.

=== Evolution ===

An interesting application of `evolve` would be with projects which don't merge, but rebase - as with Mercurial itself.  Having the [[EvolveExtension|Evolution]] enabled could follow: import the original bundle, then rebase will mark the original changes as obsolete, and when the original submitters pull from upstream back in - they will get thus rewritten history nicely sorted out, without actually loosing any of the original.

== Access-control ==

Could be set up to require full-fledged authentication, in case the review would be posted to a system where the contributor ought to have credentials for and access to.

''Needs further thought:''  Should provide easier access for the casual contributor.  This one should generally only provide means to prevent SPAM, but would be nice
to allow update of the review request by the original submitter, and only by him or her.  May include performing automatic mailing-list subscription request, if given "email" not subscribed already:
{{{
% hg review --post -m '<overview>'
Please confirm your subscription and repost your request.

% hg review --post -m '<overview>'
<review_id> - save this for further reference
}}}
If `<review_id>` is not exposed publicly, it may be used by the contributor as access-token to update the review further:
{{{
% hg review --update <review_id> ...
}}}
In the "full authentication" scenario `<review_id>` could be easily associated to and granted access for update only by the original submitter.

== Notes ==

 * Updating a review request would replace the complete change bundle.
 * May be keep old versions of review bundles, while having no UI for accessing them.