The following commit has been merged in the master branch: commit e676cee1e3d53a6bc19814628d233e5c763bbb5c Author: Bas Couwenberg <sebas...@xs4all.nl> Date: Sun Jan 5 06:09:13 2014 +0100
Further restructing of the Git tips section into the Packaging walkthrough. diff --git a/Makefile b/Makefile index a86d585..0c6307a 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ all: policy policy: xsltproc \ - --param toc.section.depth 4 \ + --param toc.section.depth 5 \ --output policy.html \ /usr/share/xml/docbook/stylesheet/docbook-xsl/xhtml/docbook.xsl \ policy.xml 2>/dev/null diff --git a/policy.xml b/policy.xml index 6666710..409efee 100644 --- a/policy.xml +++ b/policy.xml @@ -585,16 +585,16 @@ pkg-grass/ <para> Use <command>cowbuilder</command> <option>--create</option> - <option>--distribution=</option><arg choice="plain"><replaceable><distribution></replaceable></arg> - <option>--basepath=</option><arg choice="plain"><filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>.cow</filename></arg> + <option>--distribution=<replaceable><distribution></replaceable></option> + <option>--basepath=/var/cache/pbuilder/base-<replaceable><distribution></replaceable>.cow</option> to create <command>cowbuilder</command> chroots for specific distributions. </para> <para> Use <command>pbuilder</command> <option>--create</option> - <option>--distribution=</option><arg choice="plain"><replaceable><distribution></replaceable></arg> - <option>--basetgz=</option><arg choice="plain"><filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>.tgz</filename></arg> + <option>--distribution=<replaceable><distribution></replaceable></option> + <option>--basetgz=/var/cache/pbuilder/base-<replaceable><distribution></replaceable>.tgz</option> when using <command>pbuilder</command> instead. </para> <para> @@ -614,17 +614,17 @@ pkg-grass/ <para> Use <command>cowbuilder</command> <option>--create</option> - <option>--distribution=</option><arg choice="plain"><replaceable><distribution></replaceable></arg> - <option>--architecture=</option><arg choice="plain"><replaceable><architecture></replaceable></arg> - <option>--basepath=</option><arg choice="plain"><filename>/var/cache/pbuilder/base-<replaceable><distribution></replaceable>-<replaceable><architecture></replaceable>.cow</filename></arg> + <option>--distribution=<replaceable><distribution></replaceable></option> + <option>--architecture=<replaceable><architecture></replaceable></option> + <option>--basepath=/var/cache/pbuilder/base-<replaceable><distribution></replaceable>-<replaceable><architecture></replaceable>.cow</option> to create <command>cowbuilder</command> distribution and architecture specific chroots. </para> <para> Or <command>cowbuilder</command> <option>--create</option> - <option>--architecture=</option><arg choice="plain"><replaceable><architecture></replaceable></arg> - <option>--basepath=</option><arg choice="plain"><filename>/var/cache/pbuilder/base-<replaceable><architecture></replaceable>.cow</filename></arg> + <option>--architecture=<replaceable><architecture></replaceable></option> + <option>--basepath=/var/cache/pbuilder/base-<replaceable><architecture></replaceable>.cow</option> to create <command>cowbuilder</command> chroots for only specific architectures. </para> @@ -686,18 +686,66 @@ pkg-grass/ <sect3 id="git-walkthrough"> <title>Packaging walkthrough</title> <para> - + ... </para> <sect4 id="git-new-package"> <title>Starting a new package</title> <para> - + When the upstream sources are distributed as compressed + <command>tar</command> archives (<literal>tar.gz</literal>, …): + </para> + <para> +<programlisting> +<command>mkdir</command> <replaceable><package></replaceable> +<command>cd</command> <replaceable><package></replaceable> +<command>git init</command> +<command>git import-orig</command> <option>--pristine-tar</option> <filename><replaceable>/path/to/package_version.orig.tar.gz</replaceable></filename> +<command>dh_make</command> <option>-p <replaceable>package_x.y.z</replaceable></option> +</programlisting> + </para> + <para> + The above steps will create a repository with the appropriate layout + for <command>git-buildpackage</command>, with three branches: + <itemizedlist> + <listitem> + <para> + <literal>master</literal>, + where the Debian development will happen, + </para> + </listitem> + <listitem> + <para> + <literal>pristine-tar</literal>, used by the + <command>pristine-tar</command> tool during the package build + process to recreate the original tarball, and + </para> + </listitem> + <listitem> + <para> + <literal>upstream</literal>, + which will contain the upstream source. + </para> + </listitem> + </itemizedlist> + </para> + <para> + ... </para> </sect4> <sect4 id="git-existing-package"> <title>Working with existing packages</title> + <para id="debcheckout-git-track"> + When the package is already in the Debian archive, you can use the + <command>debcheckout</command> command with its + <option>--git-track='*'</option> option. + </para> <para> - + To update the <literal>master</literal>, <literal>upstream</literal> + and <literal>pristine-tar</literal> branches at once, use the + <command>gbp-pull</command> command. + </para> + <para> + ... </para> </sect4> <sect4 id="git-new-upstream"> @@ -729,48 +777,120 @@ pkg-grass/ <command>pristine-tar commit</command> <option><replaceable><tarball></replaceable></option> <option><replaceable><tag></replaceable></option> </programlisting> </para> + <para> + ... + </para> </sect4> <sect4 id="git-build-package"> <title>Building the package</title> <para> - + ... </para> </sect4> <sect4 id="git-repository-layout"> <title>Repository layout</title> <para> - + ... </para> </sect4> <sect4 id="git-push"> <title>Pushing to git.debian.org</title> <para> - + Before pushing your packaging changes to git.debian.org for the + first time, an empty repository needs to be created there. </para> + <para> + To do this connect to <literal>git.debian.org</literal>, enter the + <filename class="directory">/git/pkg-grass</filename> directory, + and run the <command>./setup-repository</command> script. + </para> + <para id="create-git-repository-on-alioth"> + Run it similar to: +<programlisting> +<command>ssh</command> git.debian.org +<command>cd</command> /git/pkg-grass +<command>./setup-repository</command> <replaceable><package></replaceable> 'Packaging of <replaceable><package></replaceable> in Debian' +</programlisting> + </para> + <para> + This will create an empty, bare, shared Git repository and setup some + hooks. Each package is kept in its own Git repository. + </para> + <para> + Now, on your local machine add the Alioth repository as a remote: + </para> + <para> +<programlisting> +<command>git remote add</command> <literal>origin</literal> <filename class="directory">git+ssh://git.debian.org/git/pkg-grass/<package>.git</filename> +</programlisting> + </para> + <para> + 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>. + </para> + <sect5 id="push-package-to-alioth"> + <title>To push the package.</title> + <para> + (make sure you've added the alioth remote!), do the following: + <command>git push</command> <option>origin master</option>. + 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> + Or use the <option>--set-upstream</option> option, helps future use of + <command>git pull</command>. +<programlisting> +<command>git</command> push --set-upstream +</programlisting> + </para> + </sect5> + <sect5 id="git-push-all-tags"> + <title>To push all your work</title> + <para> + Be sure to also do a run <command>git push</command> with + <option>--all</option>, and one with <option>--tags</option> + if you created new tags. +<programlisting> +<command>git</command> push --all --set-upstream +<command>git</command> push --tags +</programlisting> + </para> + </sect5> + <sect5 id="git-tag-release"> + <title>To tag a release</title> + <para> + <command>git tag</command> <option>debian/x.y-z</option>. + You can also easily retroactively make tags: + <command>git tag</command> <option>debian/x.y-z</option> <option><commit hash></option>. + Remember to <command>git push --tags</command>. + </para> + </sect5> </sect4> </sect3> <sect3 id="git-package-branches"> <title>Branches</title> <para> - + ... </para> </sect3> <sect3 id="git-patches"> <title>Patches</title> <para> - + ... </para> </sect3> <sect3 id="git-commit-policy"> <title>Commit policy</title> <para> - + ... </para> </sect3> <sect3 id="git-remove-package"> <title>Removing packages</title> <para> - + ... </para> </sect3> <sect3 id="git-tips"> @@ -800,62 +920,8 @@ pkg-grass/ </programlisting> </para> </sect4> - <sect4 id="new-repository-with-gbp"> - <title>To create a new local git repository</title> - <para> - When the upstream sources are distributed as compressed - <command>tar</command> archives (<literal>tar.gz</literal>, …): - </para> - <para> -<programlisting> -<command>mkdir</command> <replaceable><package></replaceable> -<command>cd</command> <replaceable><package></replaceable> -<command>git init</command> -<command>git import-orig</command> <option>--pristine-tar</option> <filename><replaceable>/path/to/package_version.orig.tar.gz</replaceable></filename> -<command>dh_make</command> <option>-p <replaceable>package_x.y.z</replaceable></option> -</programlisting> - </para> - <para> - The above steps will create a repository with the appropriate layout - for <command>git-buildpackage</command>, with three branches: - <itemizedlist> - <listitem> - <para> - <literal>master</literal>, - where the Debian development will happen, - </para> - </listitem> - <listitem> - <para> - <literal>pristine-tar</literal>, used by the - <command>pristine-tar</command> tool during the package build - process to recreate the original tarball, and - </para> - </listitem> - <listitem> - <para> - <literal>upstream</literal>, - which will contain the upstream source. - </para> - </listitem> - </itemizedlist> - </para> - </sect4> - <sect4 id="debcheckout-git-track"> - <title>To clone and follow every branch of a git repository.</title> - <para> - When the package is already in the Debian archive, you can use the - <command>debcheckout</command> command with its - <option>--git-track='*'</option> option. - </para> - <para> - To update the <literal>master</literal>, <literal>upstream</literal> - and <literal>pristine-tar</literal> branches at once, use the - <command>gbp-pull</command>. - </para> - </sect4> <sect4 id="git-track-new-branches"> - <title>To track extra upstream branches, simply check them out.</title> + <title>To track extra remote branches, simply check them out.</title> <para> With recent versions of git, the remote branch will be automatically tracked when running <command>git</command> checkout. @@ -868,43 +934,6 @@ pkg-grass/ <command>git branch</command> <option>-t pristine-tar origin/pristine-tar</option>. </para> </sect4> - <sect4 id="create-git-repository-on-alioth"> - <title>Pushing to git.debian.org, creating a new bare repository on Alioth.</title> - <para> - Before pushing to git.debian.org for the first time, - an empty repository needs to be created there. - </para> - <para> - To do this connect to <literal>git.debian.org</literal>, enter the - <filename class="directory">/git/pkg-grass</filename> directory, - and run the <command>./setup-repository</command> script. - </para> - <para id="example-create-bare-git-repository-on-alioth"> - Run it similar to: -<programlisting> -<command>ssh</command> git.debian.org -<command>cd</command> /git/pkg-grass -<command>./setup-repository</command> <replaceable><package></replaceable> 'Packaging of <replaceable><package></replaceable> in Debian' -</programlisting> - </para> - <para> - This will create an empty, bare, shared Git repository and setup some - hooks. Each package is kept in its own Git repository. - </para> - <para> - Now, on your local machine add the Alioth repository as a remote: - </para> - <para> -<programlisting> -<command>git remote add</command> <literal>origin</literal> <filename class="directory">git+ssh://git.debian.org/git/pkg-grass/<package>.git</filename> -</programlisting> - </para> - <para> - 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>. - </para> - </sect4> <sect4 id="git-change-default-branch"> <title>To change the default branch.</title> <para> @@ -916,44 +945,6 @@ pkg-grass/ of the file will be <literal>refs/heads/debian/unstable</literal>. </para> </sect4> - <sect4 id="push-package-to-alioth"> - <title>To push the package.</title> - <para> - (make sure you've added the alioth remote!), do the following: - <command>git push</command> <option>origin master</option>. - 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> - Or use the <option>--set-upstream</option> option, helps future use of - <command>git pull</command>. -<programlisting> -<command>git</command> push --set-upstream -</programlisting> - </para> - </sect4> - <sect4 id="git-push-all-tags"> - <title>To push all your work</title> - <para> - Be sure to also do a run <command>git push</command> with - <option>--all</option>, and one with <option>--tags</option> - if you created new tags. -<programlisting> -<command>git</command> push --all --set-upstream -<command>git</command> push --tags -</programlisting> - </para> - </sect4> - <sect4 id="git-tag-release"> - <title>To tag a release</title> - <para> - <command>git tag</command> <option>debian/x.y-z</option>. - You can also easily retroactively make tags: - <command>git tag</command> <option>debian/x.y-z</option> <option><commit hash></option>. - Remember to <command>git push --tags</command>. - </para> - </sect4> <sect4 id="git-debian-version-from-commit"> <title>If upstream manages his sources with Git.</title> <para> @@ -1007,7 +998,7 @@ rm ../*_source.changes <sect2 id="svn-packaging"> <title>Packaging with Subversion</title> <para> - + ... </para> <sect3 id="subversion-tips"> <title>Subversion tips</title> -- pkg-grass website _______________________________________________ Pkg-grass-devel mailing list Pkg-grass-devel@lists.alioth.debian.org http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-grass-devel