[website] 02/06: Consistently start new sentences on a new line.
Bas Couwenberg
sebastic at xs4all.nl
Sun Feb 16 00:14:38 UTC 2014
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 <sebastic at 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-gis at lists.debian.org">debian-gis at 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-gis at 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 <johndoe at 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.fsf@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
More information about the Pkg-grass-devel
mailing list