Pull requests
=============

This represents a large amount of workflow which Gitano needs to support.  Both
from the point of view of the client and the server.  Pull requests will be the
first point at which having a client tool and a server tool become important.

As such, this document is written with the assumption that there's a
client-side tool called 'gitano' which interacts with git repositories and
scripts git interactions with a Gitano server.  Most of the tool's operations
are offline against the local repository.  Sometimes they need access to the
Gitano server and those are mostly ones which devolve to direct SSH commands
and 'gitano remote sync' which pushes/pulls refs and handles merging admin
data/information.

Idealised situation Example workflow
------------------------------------

Two actors are involved in this workflow.  Alice who runs a project Frobble95
and Bob who uses Frobble95 and wants to contribute work to Alice.

Frobble95 is hosted on a Gitano instance where Bob can create a personal clone
of the repository to which he has push access.

Where steps must be performed with Internet access to the Gitano instance they
will be marked with [*], otherwise the steps are assumed to be possible
offline.  This is important for engineer-on-plane type scenarios.  Any step
which is an aynchronous notification event is marked with --> and is not
essential to the workflow but may be considered a trigger for other work.

It's worth noting that almost all stages that need internet access are 'gitano
remote sync' calls and notifications always follow such sync operations.

---- Pre-configuration.

    Alice runs 'gitano pull-request allow-incoming' to configure her Frobble95
    project to allow incoming server-side pull requests

[*] Alice runs 'gitano remote sync' to inform the server of this.

---- Some time passes

[*] Bob runs 'git clone gitano.server:alice/Frobble95'

    Bob hacks on code, making changes, eventually resulting in branch of code
    which he would like to submit to Alice.

    Bob reads a document in Frobble95/CONTRIBUTING which explains that Alice
    likes to get patches via a pull request in Gitano.

[*] Bob runs 'gitano clone gitano.server alice/Frobble95 bob/Frobble95'

--> Alice gets a notification that there's a new clone of her repo

[*] Bob runs 'gitano remote sync'

    Bob continues hacking on his code, eventually satisfied that he has
    something worth contributing.

    Bob runs 'gitano pull-request create pretty-menus' and feeds it the
    information about his branch and what it means.

    Bob runs 'gitano pull-request list' and sees his pull request ready
    for Alice to look at.

[*] Bob runs 'gitano remote sync' and gets told that his new pull-request
    has been submitted.

--> Alice gets a notification that there's a pull-request in bob's repo for
    her Frobble95 project.  The notification contains information from Bob's
    pull request along with branch related data.

[*] Alice runs 'gitano remote sync' and this pulls both the normal 
    'git remote update' branches and also all gitano admin branches local.
    Since she allowed server-side pull requests, this also pulls in the data
    which the server recorded for the pull-request from Bob.

    Alice runs 'gitano pull-request list' which lists the unfulfilled pull
    requests she has in her local repository.  These include Bob's new one.

    Alice runs 'gitano pull-request review bob/Frobble95/pretty-menus' and
    her working tree gains an uncommitted merge of the pull request which
    she proceeds to review.  She finds that the test suite no longer passes
    so she wants to reject the request.

    Alice runs 'gitano pull-request needs-work bob/Frobble95/pretty-menus'
    and explains what is needed in it.

[*] Alice runs 'gitano remote sync' and gets told that Bob has been notified
    that his pull-request needs more work.

--> Bob receives a notification that his pull-request needs more work.  This
    contains the explanation Alice provided.

[*] Bob runs 'gitano remote sync'

    Bob runs 'gitano pull-request list' and sees his pull request marked
    as needs-work.  He remembers the info in the notification and gets to it.

    Bob merges Alice's work into his branch and fixes the test suite failure
    and commits to his branch.

    Bob runs 'gitano pull-request resubmit pretty-menus' giving it more info
    about what he did to fix the test suite.

[*] Bob runs 'gitano remote sync' and gets told his request has been sent to
    Alice.

--> Alice receives a notification that there's a pull request for her to look
    at again.  This notification carries the updates from Bob.

[*] Alice runs 'gitano remote sync'

    Alice runs 'gitano pull-request list' and sees bob's updated request.

    Alice runs 'gitano pull-request review bob/Frobble95/pretty-menus' and
    reviews the changes once more.

    Alice decides the code is good and wants to commit it.  She runs
    'gitano pull-request merge bob/Frobble95/pretty-menus' and Gitano merges
    the branch and commits it, notifying her that the pull-request has been
    marked as 'merged'

[*] Alice runs 'gitano remote sync' and is informed that Bob now knows his
    pull-request succeeded.

--> Bob gets a notification that his pull-request has been merged.

[*] Bob runs 'gitano remote sync'

    Bob runs 'gitano pull-request status pretty-menus' and gets told that the
    request has been merged, and what SHA1 he can find the merged result in.