html: rework docs about operation, pledging etc.

[girocco.git] / html / mob.html

@section=site guide
@heading=About the Mob Account
@header

<!-- This file is preprocessed by cgi/html.cgi -->


<p>The <tt>mob</tt> account (the name a tribute to the paper
<a href="https://www.dreamsongs.com/MobSoftware.html">Mob Software: The Erotic Life of Code</a>)
is.a way to enable <em>anonymous push access</em> for your project.
This is largely an experiment and may be scrapped in the future if
it will not get widespread use, but we think it's an interesting try.
The idea is to provide unmoderated <em>side</em> channel for random
contributors to work on a project, with similar rationale as
e.g. Wikipedia - that given enough interested people, the quality
will grow rapidly and occassional "vandalism" will get fixed quickly.
Of course this may not work nearly as well for software, but here
we are, to give it a try.</p>

<h2>For Repository Admins</h2>

<p>How it works? First, you need to add the <tt>mob</tt> user to the
list of users allowed to push in your project. <tt>mob</tt> is a
keyless, passwordless user that anyone can use to push, without
any special setup. <strong>But</strong> this does not mean that
your project is now in the hands of raging mindless mob! The <tt>mob</tt>
user has a special restriction: it can push only to an existing
<tt>mob</tt> branch. This means that the second step you need to take
is to create a <tt>mob</tt> branch in the repository (e.g.
<code>git checkout -b mob
        &amp;&amp; git push origin mob</code>). Then the <tt>mob</tt> user
will be able to push to this and only this branch, and it won't be
able to push whatsoever until you take the second step.</p>

<p>To sum it up: Anonymous pushes are allowed <em>only</em> to the <tt>mob</tt>
branch and <em>only</em> if you add a <tt>mob</tt> user and do an initial
pushout of the <tt>mob</tt> branch.</p>

<h2>For Users</h2>

<p>After cloning the repository, do <code>git checkout mob</code> to move to the
<tt>mob</tt> branch.</p>

<p><strong>Note that you are taking a huge security risk on yourself
        if you just blindly grab the mob branch and run it on your
        system.</strong></p>

<h2>For Developers</h2>

<p>Just commit on the <tt>mob</tt> branch you've checked out and
<code>git push</code> when the time is ripe. 
Have fun and enjoy, you are making the history!</p>

<h2>Personal Mob Branches</h2>

<p>If the mob user has push permission to a project, but your user does not,
then you may push to a personal mob area.  You must <a href="/reguser.cgi"
>Register user</a> in order to use the personal mob area.</p>

<p>This personal mob area is kept under <tt>refs/mob/mob.username</tt> and
<tt>refs/mob/mob_username/</tt> and coexists independently with the single
global mob branch.  The refs in the personal mob area need not be created first
to be used and may also be freely deleted by the user.</p>

<p>Also note that changes to any refs in the personal mob area will not generate
any email notifications.</p>

<p>There are two possible ways to use the personal mob area:</p>
<ol>
<li>A single ref like <tt>mob.username</tt> or</li>
<li>Multiple refs located under <tt>mob_username/</tt></li>
</ol>

<p>As a convenience to personal mob ref users who do not also have general push
permission for a project, pushes to <tt>refs/heads/mob.username</tt> and
<tt>refs/heads/mob_username/*</tt> are automatically mapped to the corresponding
<tt>refs/mob/mob...</tt> location which makes it somewhat easier to push
branches to the personal mob area.</p>

<p>More details and examples may be found below <a href="#personalmob">here</a>
and <a href="#personalmobclone">here</a>.</p>

<h2>In Detail Examples</h2>

@@ifssh@@
<h3>Pushing to the global mob branch with ssh</h3>

<p>Nothing special is needed except to remember to set the mob user name in the push url:</p>

<blockquote><pre>
cd /tmp
git clone -b mob @@gitpullurl@@/mobexample.git
cd mobexample
git remote set-url --push origin @@mobpushurl@@/mobexample.git
echo 'It worked!' >> example.txt
git add example.txt
git commit -m 'example commit'
git push origin mob
</pre></blockquote>

<p>Note that it&#x2019;s not strictly necessary to fetch with the git protocol,
the ssh protocol can also be used for fetching.</p>
@@end@@

@@ifhttps@@
<h3 id="httpsmobpush">Pushing to the global mob branch with https</h3>

<p>In order to push with https, several things will be needed first:</p>

<ol>
@@ifcustom@@
<li>The @@nickname@@ root certificate
<p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">here</a>
and will be assumed to be saved to <tt>/tmp/@@nickname@@_root_cert.pem</tt> in the push example.
See also the <a href="@@path(htmlurl)@@/rootcert.html">Root Certificate Information</a>.</p>
<pre>
cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_root_cert.pem
</pre></li>
@@end@@

<li>The mob user certificate
<p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_mob_user.pem">here</a>
and will be assumed to be saved to <tt>/tmp/@@nickname@@_mob_user.pem</tt> in the push example.</p>
<pre>
cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_mob_user.pem
</pre></li>

<li>The mob user private key
<p>This can be fetched from <a href="@@path(webadmurl)@@/@@nickname@@_mob_key.pem">here</a>
and will be assumed to be saved to <tt>/tmp/@@nickname@@_mob_key.pem</tt> in the push example.
Normally, of course, private keys are never shared, but as described above, since everyone
is allowed to push to the mob branch the private key for the mob user must be shared with everyone.</p>
<pre>
cd /tmp &amp;&amp; curl -O @@gitwebfiles@@/@@nickname@@_mob_key.pem
</pre></li>
</ol>

<p>With the prerequisites out of the way, here&#x2019;s the mob ssh example
redone to use the smart http protocol:</p>

<blockquote><pre>
cd /tmp
git clone -b mob @@httppullurl@@/mobexample.git
cd mobexample@@ifcustom@@
git config http.sslCAInfo /tmp/@@nickname@@_root_cert.pem@@end@@
git config http.sslCert /tmp/@@nickname@@_mob_user.pem
git config http.sslKey /tmp/@@nickname@@_mob_key.pem
git remote set-url --push origin @@httpspushurl@@/mobexample.git
echo 'It worked!' >> example.txt
git add example.txt
git commit -m 'example commit'
git push origin mob
</pre>

<p style="border:thin dotted black;background-color:#eef;padding:0.5ex 1ex;max-width:90ex">If using git version
1.8.5 or later, the @@ifcustom@@<tt>http.sslCAInfo</tt>, @@end@@<tt>http.sslCert</tt> and <tt>http.sslKey</tt>
values can be set just once in the Git global configuration file so they apply only to
a specific URL (such as <tt>@@base(httpspushurl)@@</tt>)@@ifcustom@@ as shown in the example
<a href="@@path(htmlurl)@@/rootcert.html#git185">here</a>@@end@@.</p></blockquote>

<p>Note that it&#x2019;s not strictly necessary to fetch with the http protocol,
the https protocol can also be used for fetching.  However, if using a version of Git
older than version 1.8.5, it can be a bother to get the two certificates and the key set
properly without a project-specific place to configure them yet (this is not a problem
with Git version 1.8.5 or later).  See the output of <tt>git config help</tt> for
more information about configuring certificates and keys.</p>
@@end@@

<h3 id="personalmob">Pushing to the personal mob area</h3>

<p>Pushing should be configured as though your user had push permission to the project.</p>

<p>Any supported push URL may be used.</p>

<p>Here&#x2019;s a <tt>mob.$user</tt> example using the ssh protocol:</p>

<blockquote><pre>
# assume that $HOME/.ssh/config has been set up to automatically provide
# the ssh key for user alice when pushing to example.com

git clone ssh://example.com/someproject.git
cd someproject

# this is the single personal mob ref technique
git checkout -b mob.alice
git push -u origin mob.alice
</pre></blockquote>

<p>It&#x2019;s just that simple.</p>

<p>Here&#x2019;s a <tt>mob_$user/...</tt> ref example using the https protocol:</p>

<blockquote><pre>
# assume that git config http.sslCert and http.sslKey have been properly
# set up to provide the user authentication certificate for user bob
# when pushing to example.com

git clone https://example.com/someproject.git
cd someproject

# this is the multiple personal mob ref technique
git checkout -b mob_bob/master
git push -u origin mob_bob/master

# additional refs may be pushed to mob_bob/...
</pre></blockquote>

<p>Of course the ssh protocol can be used with the multiple ref technique and
the https protocol can be used with the single ref technique.</p>

<h3 id="personalmobclone">Cloning the personal mob area</h3>

<p>Since the personal mob area is intentionally sequestered under <tt>refs/mob/</tt>
a little extra work is needed to clone from a personal mob ref to start with.</p>

<p>This example will clone both user alice and user bob&#x2019;s personal mob
areas, merge them and then push them to user eve&#x2019;s personal mob area.</p>

<blockquote><pre>
# assume that $HOME/.ssh/config has been set up to automatically provide
# the ssh key for user eve when pushing to example.com
git clone -n ssh://example.com/someproject.git
cd someproject

# optionally we may first check which personal mob refs are available
git ls-remote origin | grep 'refs/mob/'
# we can see from the output that alice has a mob.alice branch and
# and bob has a mob_bob/master branch.

# since nothing under refs/mob is normally fetched we must add instructions
# to fetch the personal mob area of both alice and bob being careful to
# match the refs we need
git config --add remote.origin.fetch '+refs/mob/mob.alice:refs/remotes/origin/mob.alice'
git config --add remote.origin.fetch '+refs/mob/mob_bob/*:refs/remotes/origin/mob_bob/*'

# alternatively, this mapping will just get every personal mob ref
# but this is not really recommended
#git config --add remote.origin.fetch '+refs/mob/*:refs/remotes/origin/*'

# now fetch the new refs
git fetch

# merge mob.alice and mob_bob/master and push to mob.eve
git checkout mob.alice
git checkout mob_bob/master
git checkout -b mob.eve
git merge mob.alice
git push -u origin mob.eve
</pre></blockquote>

<p>Not so difficult, but a little bit of extra work to clone from a personal
mob area.</p>

<p>Of course a mirror clone would get everything under <tt>refs/mob/</tt> but that
would not be helpful since it would also be bare.</p>