Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
299 lines (275 sloc) 16.2 KB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns="">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Introduction &mdash; - Last updated: Sep 02, 2012</title>
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
VERSION: 'Last updated: Sep 02, 2012',
FILE_SUFFIX: '.html',
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within - Last updated: Sep 02, 2012"
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="top" title=" - Last updated: Sep 02, 2012" href="#" />
<link rel="next" title="How to follow commits" href="how_to_followcommits.html" />
<script src="_static/jquery.min.js" type="text/javascript"></script>
<script src="_static/jquery.zrssfeed.min.js" type="text/javascript"></script>
<div class="related">
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
<li class="right" >
<a href="how_to_followcommits.html" title="How to follow commits"
accesskey="N">next</a> |</li>
<li><a href="#"> - Last updated: Sep 02, 2012</a> &raquo;</li>
<div class="document">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="#">
<img class="logo" src="_static/logo.png" alt="Logo"/>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
<script type="text/javascript">$('#searchbox').show(0);</script>
<h3><a href="#">Table Of Contents</a></h3>
<li class="toctree-l1"><a class="reference internal" href="how_to_followcommits.html">How to follow commits</a></li>
<li class="toctree-l1"><a class="reference internal" href="how_to_update_this_documentation.html">How to update this page</a></li>
<li class="toctree-l1"><a class="reference internal" href="new_to_git.html">New to git?</a></li>
<li class="toctree-l1"><a class="reference internal" href="how_to_merge.html">How to merge pull requests (Admin documentation)</a></li>
<script type="text/javascript">
$(document).ready(function () {
$('#zrssfeed-collective').rssfeed('', {
limit: 5
<div id="zrssfeed-collective"></div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="introduction">
<h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<p><a class="reference external" href="">github/collective</a> started as an experiment in October 2010. Many
<a class="reference external" href="">Plone</a> developers have joined since then, which
definitely shows that development using git is gaining popularity amongst Plonistas.</p>
<div class="section" id="rules-on-github-collective">
<h1>&#8220;Rules&#8221; on github/collective<a class="headerlink" href="#rules-on-github-collective" title="Permalink to this headline">¶</a></h1>
<ul class="simple">
<li>Every member gets Github&#8217;s <tt class="docutils literal"><span class="pre">Pull</span> <span class="pre">and</span> <span class="pre">Push</span></tt> permission to all repositories.</li>
<li>Each repository has owners (team of repository owners) which have
Administrative rights to it.</li>
<li>Abuse should be reported by opening a ticket in the <a class="reference external" href=""></a> repository.</li>
<div class="section" id="how-to-get-access">
<h1>How to get access<a class="headerlink" href="#how-to-get-access" title="Permalink to this headline">¶</a></h1>
<ul class="simple">
<li>Fork <a class="reference external" href=""></a> repository, edit <tt class="docutils literal"><span class="pre">permissions.cfg</span></tt> file,
commit and push it and send us a Pull Request (see section below for details).</li>
<li>File a ticket that you want permission here:
<a class="reference external" href=""></a>
(may take longer to process than forking, because a human needs to work more here)</li>
<div class="section" id="disabling-notification-spam">
<h1>Disabling notification spam<a class="headerlink" href="#disabling-notification-spam" title="Permalink to this headline">¶</a></h1>
<p>By default you are subscribed to all new collective github repository notifications.
Unless you disable this yourself soon your inbox will contain only Github spam.</p>
<ul class="simple">
<li>Go to <a class="reference external" href=""></a></li>
<li>Select what to watch or Uncheck <em>Automatically watch</em>. But attention: latter will
disable watch for all organizations.</li>
<div class="section" id="how-to-manage-permissions-and-repositories">
<h1>How to manage permissions and repositories<a class="headerlink" href="#how-to-manage-permissions-and-repositories" title="Permalink to this headline">¶</a></h1>
<div class="section" id="process-overview">
<h2>Process Overview<a class="headerlink" href="#process-overview" title="Permalink to this headline">¶</a></h2>
<p>Permissions are stored in <a class="reference external" href="">permissions.cfg</a> file in <a class="reference external" href=""></a>
<ol class="arabic simple">
<li><strong>Fork</strong> the <a class="reference external" href=""></a>
repository to your account and then</li>
<li><strong>edit</strong> the <a class="reference external" href="">permissions.cfg</a>. If you&#8217;re done</li>
<li><strong>commit, push</strong> and create a <strong>pull request</strong>.</li>
<p>We scheduled a script that runs every hour and checks for differences and
updates them. If you can already see the new repo on the Github website but
you can't push to it, it's because the permissons haven't been set yet, have
some patience.</p>
<p>Inside <a class="reference external" href="">permissions.cfg</a> file you have a list of teams and repositories.
Team are sections starting with <tt class="docutils literal"><span class="pre">team:</span></tt> and repositories are sections
starting with <tt class="docutils literal"><span class="pre">repo:</span></tt>.</p>
<div class="section" id="instructions-on-editing-permissions-cfg">
<h2>Instructions on editing permissions.cfg<a class="headerlink" href="#instructions-on-editing-permissions-cfg" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>Push access</dt>
<dd>Add yourself to the <tt class="docutils literal"><span class="pre">contributors</span></tt> (or any other team)
Find the section <tt class="docutils literal"><span class="pre">[team:contributors]</span></tt> and insert your github username in
alphabetical order.</dd>
<dt>Create a new repository</dt>
<dd><p class="first">Add a new section in alphabetical order:</p>
<div class="highlight-python"><pre>[repo:NEW_REPOSITORY_NAME]
teams = contributors
owners = MY_USERNAME</pre>
<p class="last"><strong>Please not use the button on github website to create new repositories,
otherwise the admin team has to edit the permissions.cfg file manually because
of your laziness</strong></p>
<dt>Fork an existing repository</dt>
<dd><p class="first">In order to fork from another github user or organization add a new section:</p>
<div class="last highlight-python"><pre>[repo:REPOSITORYNAME]
teams = contributors
owners = MY_USERNAME</pre>
<dt>Not owner anymore?</dt>
<dd>You created a repository in past and now you are not owner anymore? Add
yourself to the <tt class="docutils literal"><span class="pre">owners</span> <span class="pre">=</span></tt> of the existing repository section.</dd>
<p><strong>TODO:</strong> script does not set owner the person who forked project or first
<div class="section" id="how-to-migrate-a-repository-from-svn-plone-org">
<h1>How to migrate a repository from<a class="headerlink" href="#how-to-migrate-a-repository-from-svn-plone-org" title="Permalink to this headline">¶</a></h1>
<p>Code in the <a class="reference external" href="">Plone Collective Subversion</a>
or in the <a class="reference external" href="">Plone Archetypes Subversion</a>
should be migrated to the Github collective if it is still used and development
<p>If you&#8217;re not the maintainer of the repository contact the current maintainer before.
If unsure ask at the plone-product-developers mailing-list.</p>
<p>Follow the steps below for migration.</p>
<ol class="arabic">
<li><p class="first">Add the project as a new repository to github collective <a class="reference external" href="#instructions-on-editing-permissions-cfg">as you would do for a
new one</a>. Once the pull-request was
accepted and the repository created go on with step two.</p>
<li><p class="first">On your machine use <a class="reference external" href="">svn2git to migrate on your local machine</a>
(follow also the links in there). Unfortunately Plone Administrators can not provide
an authors file (mapping from user-names to e-mail addresses) for privacy reasons.</p>
<li><p class="first">rename the trunk of the existing repository to OLD-trunk and place a
MOVED-TO-GITHUB.txt at top level of the project in svn. Add a line with the url
to the repository to the file. If you do not want to checkout the
complete subversion with all the tags and branches, you can create
this file and then use the svn import command:</p>
<div class="highlight-python"><pre>svn import MOVED-TO-GITHUB.txt</pre>
<li><p class="first">Some housekeeping</p>
<ul class="simple">
<li>Rename <tt class="docutils literal"><span class="pre">README.txt</span></tt> to <tt class="docutils literal"><span class="pre">README.rst</span></tt>, update <tt class="docutils literal"><span class="pre"></span></tt> to reflect this change,</li>
<li>Add a <tt class="docutils literal"><span class="pre"></span></tt> to include the <tt class="docutils literal"><span class="pre">*.rst</span></tt> files containing at least one line <tt class="docutils literal"><span class="pre">include</span> <span class="pre">*.rst</span></tt>,</li>
<li>Update links in <tt class="docutils literal"><span class="pre">README.rst</span></tt> to point to Github project</li>
<li>Update links on <a class="reference external" href=""> product page</a> to point to Github repository</li>
<li>optional: send a mail to the plone-product-developers mailing-list and
additional/optional tweet about it, write a line at IRC, if worth write a
blog post, ... to notify the community about it.</li>
<p>Here is an example session of moving <tt class="docutils literal"><span class="pre">collective.logbook</span></tt> to Github on OSX Mountain Lion / Macports:</p>
<div class="highlight-python"><pre># Install required software through Macports
sudo port install git-core +svn
sudo port install rb-rubygems
sudo gem install svn2git
mkdir collective.logbook &amp;&amp; cd collective.logbook
# Create repository on Github in your dashboard. Choose "collective" as the owner.
# Add yourself as collective owner of this repo by Editing this file and
# adding the new repo at the end of it
# Note: the following takes 30+ minutes to complete on fast internet connection
# as it walks through every of 150k+ commits in Collective SVN
# Wait someone accepts your permissions.cfg pull request
# It will take 5 minutes to for a script to update permission after permissions.cfg has been merged
cd collective.logbook
git push
# Now merged repository should be on Github
# Move old trunk
cd ..
svn mv -m "Moved to github"
svn mkdir -m "Moved to github"
svn co collective.logbook.old
cd collective.logbook.old
echo "Repo moved to" &gt; MOVED-TO-GITHUB.txt
svn commit -m "Added Github moved notice"</pre>
<div class="section" id="more-information">
<h1>More information<a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h1>
<div class="toctree-wrapper compound">
<li class="toctree-l1"><a class="reference internal" href="how_to_followcommits.html">How to follow commits</a></li>
<li class="toctree-l1"><a class="reference internal" href="how_to_update_this_documentation.html">How to update this page</a></li>
<li class="toctree-l1"><a class="reference internal" href="new_to_git.html">New to git?</a><ul>
<li class="toctree-l2"><a class="reference internal" href="new_to_git.html#useful-links">Useful links</a></li>
<li class="toctree-l2"><a class="reference internal" href="new_to_git.html#quick-guide">Quick guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="new_to_git.html#some-more-useful-resources">Some more useful resources</a></li>
<li class="toctree-l1"><a class="reference internal" href="how_to_merge.html">How to merge pull requests (Admin documentation)</a></li>
<div class="clearer"></div>
<div class="related">
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
<li class="right" >
<a href="how_to_followcommits.html" title="How to follow commits"
>next</a> |</li>
<li><a href="#"> - Last updated: Sep 02, 2012</a> &raquo;</li>
<div class="footer">
&copy; Copyright 2010, Rok Garbas &lt;;.
Last updated on Sep 02, 2012.
Created using <a href="">Sphinx</a> 1.1.3.