[med-svn] r6325 - trunk/community/website/docs
Charles Plessy
plessy at alioth.debian.org
Sun Mar 20 02:35:12 UTC 2011
Author: plessy
Date: 2011-03-20 02:35:12 +0000 (Sun, 20 Mar 2011)
New Revision: 6325
Modified:
trunk/community/website/docs/policy.xml
Log:
Moved most Git instructions from the policy to the tips.
Modified: trunk/community/website/docs/policy.xml
===================================================================
--- trunk/community/website/docs/policy.xml 2011-03-20 01:38:36 UTC (rev 6324)
+++ trunk/community/website/docs/policy.xml 2011-03-20 02:35:12 UTC (rev 6325)
@@ -195,17 +195,81 @@
<sect2 id="git-tips">
<title>Git tips</title>
- <para>
- To clone and follow every branch of a git repository containing a package that is already in the Debian archive, you can use the <command>debcheckout</command> command with its <command><option>--git-track='*'</option></command> option. To restrict the tracked branch to the standard ones used by <command>git-buildpackage</command>, <literal>master upstream pristine-tar</literal> can be passed instead of the wildcard.
+ <para id="new-repository-with-gbp">
+ Example to create a new git repository for a package where the upstream
+ sources are distributed as file archives (tar, zip, …):<programlisting>
+<command>mkdir</command> <filename class="directory">package</filename>
+<command>cd</command> <filename class="directory">package</filename>
+<command>git init</command>
+<command>git import-orig</command> <option>--pristine-tar</option> <filename>/path/to/package_version.orig.tar.gz</filename>
+<command>dh_make</command> <option>-p package_x.y.z</option></programlisting>
+ The above steps will create a repository with the appropriate layout for
+ <command>git-buildpackage</command>, with three branches:
+ <literal>master</literal> (where the Debian development will happen),
+ <literal>pristine-tar</literal> used by the
+ <literal>pristine-tar</literal> tool during the package build process to
+ recreate the original tarball, and <literal>upstream</literal>, which
+ will contain the upstream source.
</para>
- <para>
+ <para id="debcheckout-sets-git-options">
+ To display your name and more nicely in the Git log, you should instruct
+ Git to do so (the <option>--global</option> option is to say Git these
+ are the default parameters for every Git repository you commit to,
+ without it the settings will be per-repository only):<programlisting>
+<command>git config</command> <option><optional>--global</optional></option> <option>user.name "$DEBFULLNAME"</option>
+<command>git config</command> <option><optional>--global</optional></option> <option>user.email "$DEBEMAIL"</option></programlisting>
+ </para>
+ <para id="debcheckout-git-track">
+ To clone and follow every branch of a git repository containing a
+ package that is already in the Debian archive, you can use the
+ <command>debcheckout</command> command with its
+ <command><option>--git-track='*'</option></command> option. To restrict
+ the tracked branch to the standard ones used by
+ <command>git-buildpackage</command>, <literal>master upstream
+ pristine-tar</literal> can be passed instead of the wildcard.
+ </para>
+ <para id="git-track-new-branches">
Example commands to track new branches: <programlisting>
-git branch -t upstream origin/upstream
-git branch -t pristine-tar origin/pristine-tar</programlisting>
+<command>git branch</command> <option>-t <replaceable>upstream</replaceable> <replaceable>origin/upstream</replaceable></option>
+<command>git branch</command> <option>-t <replaceable>pristine-tar</replaceable> <replaceable>origin/pristine-tar</replaceable></option></programlisting>
</para>
- <para>
- If the <package>devscripts</package> variables <varname>DEBEMAIL</varname> and <varname>DEBFULLNAME</varname> are set, <command>debcheckout</command> will set <command>git</command>'s options <varname>user.email</varname> and <varname>user.name</varname> accordingly.
+ <para id="git-options-devscripts">
+ If the <package>devscripts</package> variables
+ <varname>DEBEMAIL</varname> and <varname>DEBFULLNAME</varname> are set,
+ <command>debcheckout</command> will set <command>git</command>'s options
+ <varname>user.email</varname> and <varname>user.name</varname>
+ accordingly.
</para>
+ <para id="git-add-alioth-branch">
+ To push changes to Alioth, a remote branch needs to be configured. This
+ is done automatically after cloning a repository, for instance with
+ <link linkend="debcheckout-git-track">debcheckout</link>. The default
+ remote branch is called <quote>origin</quote>. Here are example
+ commands to set up Alioth as a remote branch on a freshly created
+ repository:<programlisting>
+<command>git remote add</command> <literal>origin</literal> <filename class="directory">git+ssh://alioth.debian.org/git/debian-med/package.git</filename></programlisting>
+ </para>
+ <para id="create-git-repository-on-alioth">
+ There is a small script called <command>setup-repository</command> in
+ the <filename class="directory">/git/debian-med</filename> directory on
+ Alioth. <code><command>./setup-repository</command>
+ <option>packagename</option> <option>"Description of the
+ package"</option></code> will create a <filename
+ class="directory">packagename.git</filename> repository on with the
+ proper hooks set up for our team.
+ </para>
+ <para id="push-package-to-alioth">
+ To push the package (make sure you've added the alioth remote!), do the
+ following:<code><command>git push</command> <option>origin
+ master</option></code>. For the first push, it's necessary to specify
+ <option>origin master</option>. The next time you will push, a
+ <command>git push</command> will suffice.
+ </para>
+ <para id="git-push-all-tags">
+ <command>git push</command>this will only push the
+ <literal>master</literal> branch unless it is somehow related to other
+ branches), so be sure to also do a run with <option>--all</option>, and one with <option>--tags</option> if you created new tags.
+ </para>
</sect2>
<sect2 id="subversion-to-git">
@@ -408,112 +472,16 @@
the Debian Med packaging pool but it helps if the maintainer of a
certain package verifies that everything is in the right place.</para>
</sect3>
- <sect3 id="new-git-repository">
- <title>Git</title>
- <sect4 id="git-buildpackage">
- <title>Creating a local repository</title>
- <para>Just a few instructions to get you started:</para>
- <blockquote>
- <para><userinput>
- <command>mkdir</command>
- <filename class="directory">package</filename>
- </userinput></para>
- <para><userinput>
- <command>cd</command>
- <filename class="directory">package</filename>
- </userinput></para>
- <para><userinput>
- <command>git</command>
- <option>init</option>
- </userinput></para>
- <para><userinput>
- <command>git import-orig --pristine-tar</command>
- <filename>/path/to/package_version.orig.tar.gz</filename>
- </userinput></para>
- <para><userinput>
- <command>dh_make</command>
- <option>-p package_x.y.z</option>
- </userinput></para>
- </blockquote>
- <para>The above steps will create a repository with the appropriate layout for
- <command>git-buildpackage</command>, with three branches: <filename>master</filename>
- (where the Debian development will happen), <filename>pristine-tar</filename>,
- used by the <command>pristine-tar</command> tool during the package build process
- to recreate the original tarball, and <filename>upstream</filename>, which will
- contain the upstream source.</para>
- <para>To display your name and more nicely in the Git log, you should instruct
- Git to do so (the <option>--global</option> option is to say Git these are the
- default parameters for every Git repository you commit to, without it the settings
- will be per-repository only):</para>
- <blockquote>
- <para><userinput>
- <command>git config</command>
- <option>[--global]</option>
- <option>user.name "$DEBFULLNAME"</option>
- </userinput></para>
- <para><userinput>
- <command>git config</command>
- <option>[--global]</option>
- <option>user.email "$DEBEMAIL"</option>
- </userinput></para>
- </blockquote>
- <para>After you create your <filename class="directory">debian/</filename> (be sure
- to commit it!), you should add a <quote>remote</quote> to the repository. A remote is
- where the commits will be pushed to, and the default remote is called <quote>origin</quote>.</para>
- <para>If you are going to push to our Alioth repository, please do the following inside your
- local repository:</para>
- <blockquote>
- <para><userinput>
- <command>git remote add origin</command>
- <filename class="directory">git+ssh://alioth.debian.org/git/debian-med/package.git</filename>
- </userinput></para>
- </blockquote>
- <para>The next step is to create the remote repository on Alioth.</para>
- </sect4>
- <sect4 id="create-alioth-repository">
- <title>Creating the remote repository</title>
- <blockquote>
- <para><userinput>
- <command>ssh</command>
- <filename class="directory">alioth.debian.org</filename>
- </userinput></para>
- <para><userinput>
- <command>cd</command>
- <filename class="directory">/git/debian-med</filename>
- </userinput></para>
- <para><userinput>
- <command>./setup-repository</command>
- <option>packagename</option>
- <option>"Description of the package"</option>
- </userinput></para>
- </blockquote>
- <para>This will create a <filename class="directory">packagename.git</filename> repository on
- Alioth, with the proper hooks set up for our team.</para>
- </sect4>
- <sect4 id="push-package-to-alioth">
- <title>Pushing the package</title>
- <para>To push the package (make sure you've added the alioth remote!), do the following:</para>
- <blockquote>
- <para><userinput>
- <command>git push origin master</command>
- </userinput></para>
- <para><userinput>
- <command>git push</command>
- <option>--all</option>
- </userinput></para>
- <para><userinput>
- <command>git push</command>
- <option>--tags</option>
- </userinput></para>
- </blockquote>
- <para>For the first push, it's necessary to specify <quote>origin master</quote>. The next time
- you will push, a <command>git push</command> will suffice. Remember that this will only push the
- <quote>master</quote> branch (and the other two only if master is somehow related to the new
- branches), so be sure to also do a run with <option>--all</option>, and one with
- <option>--tags</option> (if you obviously changed anything in the other branches/tags).</para>
- </sect4>
- </sect3>
- </sect2>
+ <sect3 id="new-git-repo">
+ <title>New package stored in a Git repository.</title>
+ <para>
+ Git repositories should be stored in the
+ <filename class="directory">/git/debian-med</filename> directory on Alioth and created with the <link
+ linkend="create-git-repository-on-alioth"><command>setup-repository</command></link>
+ script available there.
+ </para>
+ </sect3>
+ </sect2>
<sect2 id="building-and-tagging">
<title>Building and tagging the packages</title>
<sect3 id="building">
More information about the debian-med-commit
mailing list