This is an automated email from the git hooks/post-receive script. sebastic-guest pushed a commit to branch master in repository website.
commit e1973928a4fff77b27d1fcdf69e181f354f468ee Author: Bas Couwenberg <sebas...@xs4all.nl> Date: Sun Feb 16 01:09:18 2014 +0100 Consistently start new sentences on a new line. --- policy.xml | 275 ++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 152 insertions(+), 123 deletions(-) diff --git a/policy.xml b/policy.xml index d7981eb..9a6c072 100644 --- a/policy.xml +++ b/policy.xml @@ -59,8 +59,8 @@ </para> <para> Thanks to efforts of the Debian GIS team, we currently have many - exciting GIS packages in Debian's main archives. Other programs - are well along their way to being included in the archive. + exciting GIS packages in Debian's main archives. + Other programs are well along their way to being included in the archive. </para> <para> The Debian source packages maintained by the Debian GIS team are also @@ -108,17 +108,20 @@ </para> <para> When working on these, you will find immediate targets for improvements - of the original English versions, too. For these, though, you need access - to Debian GIS's source code repository. Very welcome are tutorials that - guide Debian users towards the use of packages to their immediate benefit. - You may also consider to write respective articles for Magazines, be they - online or in print. + of the original English versions, too. + For these, though, you need access to Debian GIS's source code repository. + Very welcome are tutorials that guide Debian users towards the use of + packages to their immediate benefit. + You may also consider to write respective articles for Magazines, + be they online or in print. </para> <para> This policy is a work in progress, and attempts to document best - practices which evolve and change over time. Different people tend to do - things in different ways. If your way diverges, you may want to document - it here so that others can benefit. Please send any comments or ideas to + practices which evolve and change over time. + Different people tend to do things in different ways. + If your way diverges, you may want to document it here + so that others can benefit. + Please send any comments or ideas to <ulink url="mailto:debian-...@lists.debian.org">debian-...@lists.debian.org</ulink>. </para> <sect2 id="membership"> @@ -184,15 +187,16 @@ <sect1 id="repositories"> <title>Repositories</title> <para> - We use Git and Subversion (SVN) repositories, hosted by Debian. You can - have a look at each repository through Alioth's web interfaces: + We use Git and Subversion (SVN) repositories, hosted by Debian. + You can have a look at each repository through Alioths web interfaces: <ulink url="http://anonscm.debian.org/gitweb/">gitweb</ulink> and <ulink url="http://anonscm.debian.org/viewvc/pkg-grass/">ViewVC</ulink>. </para> <para> The Git repository is the primary location for our source packages these - days. However, the Subversion repository is still used for some packages - that have not migrated to Git yet. + days. + However, the Subversion repository is still used for some packages that + have not migrated to Git yet. </para> <warning id="umask"> <para> @@ -258,10 +262,10 @@ <title>SSH tips</title> <para id="ssh-config"> You can avoid specifying your Alioth user name by setting it in - <filename>~/.ssh/config</filename> as follows. Note that in that case, - with <command>debcheckout</command> you can replace the - <option>--user</option> option by the <option>-a</option> option, for - a shorter typing. + <filename>~/.ssh/config</filename> as follows. + Note that in that case, with <command>debcheckout</command> you can + replace the <option>--user</option> option by the + <option>-a</option> option, for less typing. <programlisting> Host *.debian.org User your-user-name @@ -269,8 +273,9 @@ Host *.debian.org </para> <para id="ssh-add"> You can avoid typing your SSH password again and again using the - <command>ssh-add</command> command. On remote connections the SSH agent - needs to be enabled with the command <command>eval</command> + <command>ssh-add</command> command. + On remote connections the SSH agent needs to be enabled with the + command <command>eval</command> <option>$(</option><command>ssh-agent</command><option>)</option>. </para> <para id="wiki-alioth"> @@ -362,9 +367,10 @@ pkg-grass/ <command>git-buildpackage</command> can be set to a directory layout similar to the one we use with <command>svn-buildpackage</command> by using the <literal>export-dir</literal> and - <literal>tarball-dir</literal> options. However those settings should - only be in a system-wide or user-wide <filename>gbp.conf</filename> - file and not the one committed in the Git repository. + <literal>tarball-dir</literal> options. + However those settings should only be in a system-wide or user-wide + <filename>gbp.conf</filename> file and not the one committed in the + Git repository. </para> </sect3> <sect3 id="other-git-branches"> @@ -524,20 +530,21 @@ pkg-grass/ For packages where we set the <literal>mergeWithUpstream</literal> property, which excludes the upstream sources, there is no easy way to prepare a Git repository from our Subversion repository that would look - like the package was always managed in Git. Nevertheless, the following - recipe will generate a Git repository that contains all the history of - the debian directory, plus a collection of selected upstream source - releases. + like the package was always managed in Git. + Nevertheless, the following recipe will generate a Git repository that + contains all the history of the debian directory, plus a collection of + selected upstream source releases. </para> <itemizedlist> <listitem> <para> Start the conversion as explained in the <ulink url="http://wiki.debian.org/Alioth/Git#ConvertaSVNAliothrepositorytoGit">Alioth/Git</ulink> - page of the Debian wiki. To be consistent with a later usage of - <command>git-buildpackage</command>, it is preferable to prefix the - tag names <quote>debian</quote>. During this conversion, you can - take advantage of the file + page of the Debian wiki. + To be consistent with a later usage of + <command>git-buildpackage</command>, + it is preferable to prefix the tag names <quote>debian</quote>. + During this conversion, you can take advantage of the file <filename>/trunk/community/infrastructure/comitters</filename> in the Subversion repository, and expand it if necessary. </para> @@ -577,12 +584,12 @@ pkg-grass/ It is also possible to prepare a Git repository containing some of the package's history using the command <command>git-import-dscs --debsnap</command> from the helper toolkit - <command>git-buildpackage</command>. This will download all the versions - of a package available in + <command>git-buildpackage</command>. + This will download all the versions of a package available in <ulink url="http://snapshot.debian.org">snapshot.debian.org</ulink> - and create tags for each of them. Note that as this paragraph is - written, the tool is not aware that <literal>backports</literal> - should be a different branch. + and create tags for each of them. + Note that as this paragraph is written, the tool is not aware that + <literal>backports</literal> should be a different branch. </para> </sect2> </sect1> @@ -592,9 +599,11 @@ pkg-grass/ <title>Newcomer guidelines for building proper Debian packages</title> <para> Some newcomers tend to go the create DEBIAN dir, move files around and - `dpkg-deb -b` way to create Debian packages. Short answer: Forget about - this. The only way to the official Debian mirror leads via proper - source packages. The right way to build Debian packages is described in + `dpkg-deb -b` way to create Debian packages. + Short answer: Forget about this. + The only way to the official Debian mirror leads via proper source + packages. + The right way to build Debian packages is described in the <ulink url="http://www.debian.org/doc/manuals/maint-guide/">Debian New Maintainers' Guide</ulink>. </para> <para> @@ -682,9 +691,8 @@ pkg-grass/ <command>pristine-tar</command> (<ulink url="http://packages.qa.debian.org/p/pristine-tar.html">PTS</ulink>, <ulink url="http://manpages.debian.net/cgi-bin/man.cgi?query=pristine-tar">man</ulink>) - is used to allow byte-identical - recreation of the original tarball from the - <literal>upstream</literal> branch. + is used to allow byte-identical recreation of the original + tarball from the <literal>upstream</literal> branch. </para> <para> Use <command>git-buildpackage</command>'s @@ -908,13 +916,15 @@ Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder <command>git-import-orig</command> makes it easy to update of the <literal>upstream</literal> branch using upstream releases distributed as a compressed archive, and to merge these changes in - the <literal>master</literal> branch. Its option - <command>--pristine-tar</command> is useful for stabilizing the MD5 sum - of the "<filename>orig.tar.gz</filename>" produced when building a - source package from the repository alone (not doing so results in - archive rejection of package updates). With recent versions of - <command>git-buildpackage</command>, it is often unnecessary to rename - the freshly downloaded original upstream archive. + the <literal>master</literal> branch. + Its option <command>--pristine-tar</command> + is useful for stabilizing the MD5 sum of the + "<filename>orig.tar.gz</filename>" produced when building a source + package from the repository alone (not doing so results in archive + rejection of package updates). + With recent versions of <command>git-buildpackage</command>, + it is often unnecessary to rename the freshly downloaded original + upstream archive. </para> <para> If you do not use <command>git-buildpackage</command>, please use @@ -1054,7 +1064,8 @@ Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder </para> <para> This will create an empty, bare, shared Git repository and setup some - hooks. Each package is kept in its own Git repository. + hooks. + Each package is kept in its own Git repository. </para> <para> See the <link linkend="ssh-config">SSH tips</link> section for how to configure the default <command>ssh</command> username for <literal>git.debian.org</literal>. @@ -1154,8 +1165,8 @@ Cmnd_Alias PBUILDERS=/usr/sbin/pbuilder, /usr/sbin/cowbuilder <para> That is, either include the changelog entry with each commit using <command>dch</command>, - or finish your work by updating the changelog, e.g. using - <command>gbp-dch</command>. + or finish your work by updating the changelog, + e.g. using <command>gbp-dch</command>. </para> </sect4> </sect3> @@ -1285,33 +1296,40 @@ alias <command>svn-bt</command>='svn-buildpackage --svn-tag' <para id="svn-mergewithupstream"> <command>svn-inject <replaceable>-o</replaceable></command> sets up the <literal>mergeWithUpstream</literal> property for the SVN directories - where packages are stored. In case <command>svn-inject</command> - was not used, you can do it by hand with the command - <command>svn propset</command> - <replaceable>mergeWithUpstream</replaceable> - <replaceable>1</replaceable> <replaceable>debian</replaceable>. + where packages are stored. + In case <command>svn-inject</command> was not used, + you can do it by hand with the command: +<programlisting> +<command>svn propset</command> <literal>mergeWithUpstream</literal> <literal>1</literal> <literal>debian</literal> +</programlisting> </para> <para id="download-upstream-source"> - To download the upstream sources (if there is a - <filename>debian/watch</filename> file): - <command>echo "origDir=.." >> .svn/deb-layout && uscan --force-download</command>. - Alternatively, you can try - <command>debian/rules get-orig-source</command>. + To download the upstream sources + (if there is a <filename>debian/watch</filename> file): +<programlisting> +<command>echo</command> <literal>"origDir=.."</literal> >> <filename>.svn/deb-layout</filename> && <command>uscan</command> <option>--force-download</option> +</programlisting> + Alternatively, you can try: +<programlisting> +<command>make</command> <option>-f</option> <filename>debian/rules</filename> <literal>get-orig-source</literal> +</programlisting> </para> <para id="svn-write-access"> If you're a Debian Developer or a member of the pkg-grass group on Alioth, you can commit your changes: <command>svn commit</command> - (also <command>svn ci</command>). Otherwise, you can ask to be added - to the group (see the <link linkend="membership">Membership</link> - section), or send the result of <command>svn diff</command> to the + (or <command>svn ci</command>). + Otherwise, you can ask to be added to the group + (see the <link linkend="membership">Membership</link> section), + or send the result of <command>svn diff</command> to the <ulink url="mailto:debian-...@lists.debian.org">mailing list</ulink> - (<command>gzip -9</command> it, if it's too large). + (<command>gzip</command> <option>-9</option> it, if it's too large). </para> <para id="svn-tag-release"> It may happen that a package version has been uploaded to Debian repositories, and you forgot to tag the last build with - <command>svn-buildpackage --svn-tag</command>. You can tag this - package also retroactively. A first step, creating the tags directory, + <command>svn-buildpackage --svn-tag</command>. + You can tag this package also retroactively. + A first step, creating the tags directory, can be achieved in two ways: either create it locally as sibling of <filename class="directory">trunk/</filename> with <command>svn mkdir</command> @@ -1386,11 +1404,13 @@ lintian ../build-area/*changes </para> <para> Please keep in mind issues like the possibility to upgrade to the next - Ubuntu stable release. Packages that are backports can be made + Ubuntu stable release. + Packages that are backports can be made <ulink url="http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version">inferior in version by using a tilde</ulink>. If the package contains additional development, a version number without the tilde will make it higher, but not as high as the next Debian - revision. For example: + revision. + For example: <programlisting> 2.12.0-1~natty1 (backport in PPA) < 2.12.0-1 (from Debian in Ubuntu) @@ -1434,12 +1454,12 @@ lintian ../build-area/*changes <title>R packages</title> <para> <ulink url="http://packages.qa.debian.org/r-base-core">GNU R</ulink> - sometimes introduces backward incompatibilities, so the current practice - is to make packages depend on versions equal or higher to the one - against which they were built. When using <code>r-base-dev</code>, - this can be achieved by adding the substitution variable - <code>${R:Depends}</code> in the <literal>Depends</literal> field of - the binary package. + sometimes introduces backward incompatibilities, + so the current practice is to make packages depend on versions equal or + higher to the one against which they were built. + When using <code>r-base-dev</code>, this can be achieved by adding the + substitution variable <code>${R:Depends}</code> in the + <literal>Depends</literal> field of the binary package. </para> </sect2> </sect1> @@ -1457,10 +1477,13 @@ lintian ../build-area/*changes </para> <para> The tasks files are not hosted in the Debian GIS repositories, but in the - Debian Blends repository. Interested members of the Debian GIS project on - the Alioth forge can request write access to the Blends repository. - You can easily check out its sources with the command - <command>debcheckout -a debian-gis</command>. + Debian Blends repository. + Interested members of the Debian GIS project on the Alioth forge can + request write access to the Blends repository. + You can easily check out its sources with the command: +<programlisting> +<command>debcheckout</command> <option>-a</option> <literal>debian-gis</literal> +</programlisting> </para> <para> The syntax of the tasks files is very similar to Debian control files, @@ -1540,8 +1563,9 @@ Uploaders: <replaceable>John Doe <john...@example.com></replaceable>, <title>Standards-Version</title> <para> Please always use the latest unless there are concerns for - backporting. If no changes are needed, please indicate this - fact in the changelog, and increment the value of the field. + backporting. + If no changes are needed, please indicate this fact in the + changelog, and increment the value of the field. <programlisting> Standards-Version: 3.9.5 </programlisting> @@ -1706,10 +1730,11 @@ pristine-tar = True <para> This file is recommended by the Policy (<ulink url="http://www.debian.org/doc/debian-policy/ch-source.html#s-readmesource">§ 4.14</ulink>) - from version 3.8.0 for documenting source package handling. Please - follow the recommendation. For instance, this file is needed when we - use a patch system, when the upstream sources are in another format - than gzipped tar archive, when we repack the sources,… + from version 3.8.0 for documenting source package handling. + Please follow the recommendation. + For instance, this file is needed when we use a patch system, + when the upstream sources are in another format than gzipped + tar archive, when we repack the sources,… </para> </sect2> <sect2 id="debian-readme-test"> @@ -1717,17 +1742,19 @@ pristine-tar = True <para> This file was (<ulink url="http://lists.debian.org/debian-devel-announce/2011/01/msg00006.html">recommended by the Security team</ulink>) - for describing to others than the regular maintainer how the package's + for describing to others than the regular maintainer how the package functionality can properly be tested. </para> </sect2> <sect2 id="debian-source-format"> <title><filename>debian/source/format</filename></title> <para> - This file should contain <quote><literal>3.0 (quilt)</literal></quote> in - order to use this source format. Other formats should be avoided unless - they bring a specific advantage. + This file should contain <quote><literal>3.0 (quilt)</literal></quote>. + Other formats should be avoided unless they bring a specific advantage. </para> +<programlisting> +3.0 (quilt) +</programlisting> </sect2> <sect2 id="debian-source-option"> <title><filename>debian/source/option</filename></title> @@ -1790,12 +1817,14 @@ pristine-tar = True <filename class="directory">/git/pkg-grass</filename> directory on Alioth and created with the <link linkend="git-repository-on-alioth"><command>setup-repository</command></link> - script available there. There, they must give write access to the - <literal>pkg-grass</literal> Alioth group and all the Debian - Developers, with appropriate Unix permissions (including SGID bit on - directories) and ACLs. See - <filename class="directory">/git/pkg-grass</filename> itself as an - example. <command>setup-repository</command> does this automatically. + script available there. + On Alioth write access must be given to the + <literal>pkg-grass</literal> group and all the Debian Developers, + with appropriate Unix permissions (including SGID bit on directories) + and ACLs. + See <filename class="directory">/git/pkg-grass</filename> itself as + an example. + <command>setup-repository</command> does this automatically. </para> <para> Git repositories managed with a helper tool should announce it. For @@ -1841,18 +1870,18 @@ pristine-tar = True <para> Once you injected a new package please make sure that it is mentioned in the appropriate <link linkend="tasks">tasks</link> file in the - source of the <package>debian-gis</package> Blend package. Some team - members watch the changes in the Debian GIS packaging pool but it helps - if the maintainer of a new package verifies that everything is in the - right place. + source of the <package>debian-gis</package> Blend package. + Some team members watch the changes in the Debian GIS packaging pool + but it helps if the maintainer of a new package verifies that everything + is in the right place. </para> </sect2> <sect2 id="building-and-tagging"> <title>Building and tagging the packages</title> <para> - We prefer that uploaded packages are built in a chroot, to provide - similar build environment to the whole team. After upload, please - <link linkend="vcs-tags">tag</link> the + We prefer that uploaded packages are built in a chroot, + to provide similar build environment to the whole team. + After upload, please <link linkend="vcs-tags">tag</link> the <link linkend="git-tag-release">Git</link> or <link linkend="svn-tag-release">Subversion</link> repository. </para> @@ -1862,25 +1891,27 @@ pristine-tar = True <para> Often happens that the upstream code doesn't fit well into the Debian distribution: be this wrong paths, missing features, anything that - implies editing the source files. When you directly edit upstream's - source files, your changes will be put into a .diff.gz file if you use - the <literal>1.0</literal> source format and in a monolithic patch if - you use the <literal>3.0 (quilt)</literal> format. To better organize - the patches and group the by function, please use a patch handling - system which keeps patches under the - <filename class="directory">debian/patches</filename> directory. + implies editing the source files. + When you directly edit upstreams source files, your changes will be put + into a .diff.gz file if you use the <literal>1.0</literal> source format + and in a monolithic patch if you use the <literal>3.0 (quilt)</literal> + format. + To better organize the patches and group the by function, please use a + patch handling system which keeps patches under the + <filename class="directory">debian/patches/</filename> directory. </para> <para> The <literal>3.0 (quilt)</literal> dpkg source format provides its own - patch system. Apart from this, the most popular is - <command>quilt</command>. <literal>simple-patchsys</literal>, - from the <package>CDBS</package> package, is deprecated since version - <literal>0.4.85</literal>. <command>dpatch</command> has been popular - as well, but is not compatible with the <literal>3.0 (quilt)</literal> + patch system. + Apart from this, the most popular is <command>quilt</command>. + <literal>simple-patchsys</literal>, from the <package>CDBS</package> + package, is deprecated since version <literal>0.4.85</literal>. + <command>dpatch</command> has been popular as well, + but is not compatible with the <literal>3.0 (quilt)</literal> source format and is <ulink url="http://lists.debian.org/878vqt6was....@luthien.mhp">planned to be removed 2017</ulink>. - Please don't use any other patch system in Debian GIS, unless - absolutely necessary. + Please don't use any other patch system in Debian GIS, + unless absolutely necessary. </para> <sect3 id="quilt"> <title>Using <command>quilt</command></title> @@ -1918,23 +1949,21 @@ QUILT_PATCHES="debian/patches" </para> <para> Now start editing files, with: - </para> <programlisting> <command>quilt edit</command> <replaceable><file></replaceable> </programlisting> + </para> <para> And repeat the process for each file the patch is involved with. At the end, run: - </para> <programlisting> <command>quilt refresh</command> </programlisting> - <para> This will compare the noted state of the edited files with the current state, and will produce a patch in - <filename>debian/patches</filename>. Remember: the patch is - currently applied (you can check this with - <command>quilt applied</command>). + <filename>debian/patches</filename>. + Remember: the patch is currently applied + (you can check this with <command>quilt applied</command>). </para> </sect4> <sect4 id="quilt-apply"> -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-grass/website.git _______________________________________________ Pkg-grass-devel mailing list Pkg-grass-devel@lists.alioth.debian.org http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-grass-devel