[med-svn] [policy] 01/01: docbook->ReStructured Text
Michael Crusoe
misterc-guest at moszumanska.debian.org
Sat Feb 6 13:32:28 UTC 2016
This is an automated email from the git hooks/post-receive script.
misterc-guest pushed a commit to branch master
in repository policy.
commit 648d7bcc1e8c759885574f51759c52943c32db0a
Author: Michael R. Crusoe <crusoe at ucdavis.edu>
Date: Sat Feb 6 05:30:50 2016 -0800
docbook->ReStructured Text
---
policy.rst | 1205 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 1205 insertions(+)
diff --git a/policy.rst b/policy.rst
new file mode 100644
index 0000000..bbf6c83
--- /dev/null
+++ b/policy.rst
@@ -0,0 +1,1205 @@
+|image0|
+
+Introduction
+============
+
+Debian Med is a “`Debian Pure
+Blend <http://blends.alioth.debian.org/blends>`__” with the aim to
+develop Debian into an operating system that is particularly well fit
+for the requirements for medical practice and research.
+
+The Debian Med project presents packages that are associated with
+medicine, pre-clinical research, and life sciences. Its developments are
+mostly focused on three areas for the moment: medical practice, imaging
+and bioinformatics.
+
+Over the previous years, several initiatives have spawned that address
+the scientific disciplines like chemistry or bioinformatics. Debian Med
+is not a competition to these efforts but a platform to present the
+packages to the community as a Debian Pure Blend.
+
+How to Contribute
+=================
+
+From the developer to the user, there is a long chain of tasks in which
+we always welcome participation. First we must keep ourselves informed
+about the software landscape in biology and medicine. Software to be
+packaged is chosen according to criteria such as users' need and the
+consistency of the distribution.
+
+Once in Debian, the software is monitored for its quality and bugs are
+fixed, if possible in collaboration with the upstream maintainer(s). All
+this work would not be very useful if it remains confidential.
+
+We also dedicate some time to advertise it to the world via
+`www.debian.org <http://www.debian.org>`__ and to ease the integration
+of new members.
+
+Please contact us on debian-med at lists.debian.org if you want to help to
+make medical and biological software available to Debian users. Read the
+`Membership <#membership>`__ section if you're interested in joining us.
+
+If you speak a language other than English, you can contribute rightaway
+with translations of package descriptions at
+`ddtp.debian.net <http://ddtp.debian.net>`__.
+
+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 Med'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.
+
+Membership
+----------
+
+To request membership to this group, please go on our `Alioth
+page <http://alioth.debian.org/projects/debian-med>`__, or directly
+follow this
+`link <http://alioth.debian.org/project/request.php?group_id=30063>`__.
+Remember that you must have an Alioth account before requesting
+membership (see `here <http://alioth.debian.org/account/register.php>`__
+to request an Alioth account).
+
+Essential readings
+------------------
+
+- The `Debian Policy <http://www.debian.org/doc/debian-policy/>`__:
+ packages must conform to it.
+
+- The `Developers
+ Reference <http://www.debian.org/doc/developers-reference/>`__:
+ details best packaging practices.
+
+- The `New Maintainer's
+ Guide <http://www.debian.org/doc/maint-guide/>`__: puts a bit of the
+ two above in practice.
+
+- The `Debian Med
+ Policy <http://debian-med.alioth.debian.org/docs/policy.html>`__
+ (this document): explains how the work is organised in our team.
+
+Contributing to this Policy
+---------------------------
+
+This policy is itself maintained in SVN and all team members have write
+access to its repository.
+
+::
+
+ svn checkout svn+ssh://svn.debian.org/svn/debian-med/trunk/community/website/docs
+ Make changes to docs/policy.xml, commit.
+ Publish using the following command:
+ make publish
+
+
+Repositories
+============
+
+We use Subversion (SVN) and Git repositories, hosted by Debian. You can
+have a look at each repository through Alioth's web interfaces:
+`ViewVC <http://svn.debian.org/viewsvn/debian-med/trunk/>`__ and
+`gitweb <http://anonscm.debian.org/gitweb/?a=project_list;pf=debian-med>`__
+or `cgit <http://anonscm.debian.org/cgit/debian-med>`__.
+
+ **Warning**
+
+ For most direct operations on the repositories in Alioth, an
+ ``umask`` of ``002`` is necessary to avoid problems of missing write
+ permission to the other team members.
+
+Give me the source!
+-------------------
+
+To check the sources of a package (referred as *<package>* below) in our
+repositories, use the ``debcheckout`` command, from the
+`devscripts <http://packages.debian.org/devscripts>`__ package.
+
+- If you are a member of Debian Med or a Debian developer, with account
+ name *<username>*, you have write permission.
+
+ If the package is already in the archive:
+
+ ::
+
+ debcheckout --user <username> --git-track '*' <package>
+
+ For draft packages that are only on Alioth:
+
+ ::
+
+ debcheckout --user <username> svn://svn.debian.org/debian-med/trunk/packages/<package>/trunk <package>
+ debcheckout --user <username> git://git.debian.org/debian-med/<package>.git --git-track '*'
+
+ For packages managed with Git, the option ``--git-track`` ensures
+ that the clone has all the branches tracked. This is needed when
+ using the `gbp buildpackage <#git-buildpackage>`__ helper.
+ Alternatively to ``debcheckout``, the command ``gbp clone`` will also
+ track the relevant branches:
+
+ ::
+
+ gbp clone git+ssh://git.debian.org/git/debian-med/<package>.git
+
+- For read-only access with ``debcheckout``, remove the ``--user``
+ option. With ``gbp clone``, use an anonymous URL like the following:
+
+ ::
+
+ gbp clone git://anonscm.debian.org/debian-med/<package>.git
+
+SSH tips
+--------
+
+You can avoid specifying your Alioth user name by setting it in
+``~/.ssh/config`` as follows. Note that in that case, with
+``debcheckout`` you will can replace the ``--user`` option by the ``-a``
+option, for a shorter typing.
+
+::
+
+ Host *.debian.org
+ User your-user-name
+
+You can avoid typing your SSH password again and again using the
+``ssh-add`` command. On remote connections the SSH agent needs to be
+enabled with the command ``eval
+ $(ssh-agent)``.
+
+In case of trouble getting SSH working it is a good idea to read `this
+wiki article <http://wiki.debian.org/Alioth/SSH>`__.
+
+Subversion repository structure
+-------------------------------
+
+The SVN repository is structured as follows:
+
+::
+
+ debian-med/
+ └ trunk/
+ ├ community/
+ │ ├ debtags/
+ │ ├ infrastructure/
+ │ └ website/
+ └ packages/
+ ├ <package A>/
+ │ ├ branches/
+ │ ├ tags/
+ │ └ trunk/
+ │ └ debian/
+ ├ <package B>/
+ │ ├ branches/
+ │ ├ tags/
+ │ └ trunk/
+ │ └ debian/
+ …
+
+Subversion tips
+---------------
+
+For Debian Med packages maintained with Subversion, many of us use
+``svn-buildpackage`` and we recommend it to beginners. The following
+aliases may be useful:
+
+::
+
+ alias svn-b='svn-buildpackage -us -uc --svn-ignore'
+ alias svn-br='svn-b --svn-dont-purge --svn-reuse'
+ alias svn-bt='svn-buildpackage --svn-tag'
+
+``svn-inject -o`` sets up the ``mergeWithUpstream`` property for the SVN
+directories where packages are stored. In case ``svn-inject`` was not
+used, you can do it by hand with the command ``svn propset
+ mergeWithUpstream
+ 1 debian``.
+
+To download the upstream sources (if there is a ``debian/watch`` file):
+``echo
+ "origDir=.." >> .svn/deb-layout && uscan
+ --force-download``. Alternatively, you can try
+``debian/rules get-orig-source``.
+
+If you're a Debian developer or a member of the Debian Med group on
+Alioth, you can commit your changes: ``svn commit`` (also ``svn ci``).
+Otherwise, you can ask to be added to the group (see the
+`Membership <#membership>`__ section), or send the result of
+``svn diff`` to the `mailing
+list <mailto:debian-med at lists.debian.org>`__ (``gzip -9`` it, if it's
+too large).
+
+It may happen that a package version has been uploaded to Debian
+repositories, and you forgot to tag the last build with
+``svn-buildpackage --svn-tag``. 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 ``trunk/``
+with ``svn mkdir tags``, and commit with ``svn commit``, or create it
+remotely with
+``svn mkdir svn+ssh://user@svn.debian.org/svn/debian-med/trunk/packages/<package>/tags``.
+After the tags directory has been created, you're ready to tag the
+package: ``svn-buildpackage --svn-tag-only --svn-noautodch``. The
+``--svn-noautodch`` avoids ``debian/changelog`` to be marked as
+``UNRELEASED``.
+
+Here is an example session where a package is prepared manually:
+
+::
+
+ # Check out debian-med/trunk, cd to debian-med/trunk/packages
+ # Create new project folder with
+ svn mkdir projectname
+ svn mkdir projectname/trunk
+
+ # Put orig.tar.gz in place
+ mv some_version.orig.tar.gz projectname
+
+ # Inform svn-buildpackage about the location of the orig.tar.gz
+ echo "origDir=.." > projectname/trunk/.svn/deb-layout
+
+ # Untar source tree for development
+ cd projectname
+ tar xzvf some_version.orig.tar.gz
+ cd some-version # entering the unpackaged source tree
+ if [ ! -d debian ]; then svn export svn://anonscm.debian.org/svn/debian-med/trunk/package_template debian ; fi
+ mv debian ../trunk
+ ln -s ../trunk/debian .
+
+ # continue development
+ fakeroot ./debian/rules binary
+
+ # until it works, finally
+ cd ..
+
+ # debian directory is the only thing that is stored in svn, to be merged with upstream
+ svn propset mergeWithUpstream 1 trunk/debian
+
+ # See if things can be compiled via svn-buildpackage
+ cd trunk
+ svn-buildpackage -uc -us
+
+ # check build
+ lintian ../build-area/*changes
+
+Common Git repository structures
+--------------------------------
+
+The area on Alioth that contains the Git repositories
+(``/git/debian-med``) is not itself structured, but the repositories can
+be arranged in different possible layouts.
+
+``gbp buildpackage``
+~~~~~~~~~~~~~~~~~~~~
+
+Most of our packages using Git and stored in Alioth are managed
+following the standard layout of the ``gbp buildpackage`` helper. The
+``master`` branch contains the full source package. The ``upstream``
+branch contains the upstream source, after repacking when necessary
+(non-free files, large convenience code copies, …). The ``pristine-tar``
+contains the data necessary to recreate an original tarball from the
+repository with a reproducible checksum.
+
+Debian releases are tagged with names like ``debian/debianversion`` and
+upstream releases are tagged with names like
+``upstream/upstreamversion``.
+
+``gbp buildpackage`` can be set to a directory layout similar to the one
+we use with ``svn-buildpackage`` by using the ``export-dir`` and
+``tarball-dir`` options. However those settings should only be in a
+system-wide or user-wide ``gbp.conf`` file and not the one committed in
+the Git repository.
+
+Social Git
+~~~~~~~~~~
+
+For some projects, like the ones hosted on
+`GitHub <http://www.github.com>`__ or
+`Gitorious <http://www.gitorious.com>`__, it may be easier to forward
+changes made in the Debian package if this one is itself mirrored on the
+same platform, as a clone. In that case, the layouts may vary from
+package to packages, and the branch that contains the Debian work will
+probably not be the master one. If it is not the `default
+branch <#git-change-default-branch>`__, It must be indicated in the `VCS
+URL <#vcs-url>`__ with the ``-b`` option.
+
+Even when you are not using ``gbp buildpackage``, please include a
+```debian/gbp.conf`` <#debian-gbp.conf>`__, to document the layout of
+the repository.
+
+Other branches
+~~~~~~~~~~~~~~
+
+Changes uploaded to other distributions than ``unstable`` can be stored
+in other branches, named for instance ``experimental``, ``stable``, etc.
+
+Git tips
+--------
+
+Set the devscripts variables ``DEBEMAIL`` and ``DEBFULLNAME``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``debcheckout`` will then set ``git``'s options ``user.email`` and
+``user.name`` accordingly.
+
+Configure Git to commit using your packager name and address.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``--global`` 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:
+
+::
+
+ git config --global user.name "$DEBFULLNAME"
+ git config --global user.email "$DEBEMAIL"
+
+To create a new local git repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before you create a new git repository you probably want to check
+whether your target project just exists.
+`Here <http://anonscm.debian.org/gitweb/?pf=debian-med>`__ is an
+overview about all projects packaged in Git by the Debian Med team.
+
+When the upstream sources are distributed as compressed ``tar`` archives
+(``tar.gz``, …):
+
+::
+
+ mkdir package
+ cd package
+ git init
+ gbp import-orig --pristine-tar /path/to/package_version.orig.tar.gz
+ svn export svn://anonscm.debian.org/svn/debian-med/trunk/package_template debian
+
+The above steps will create a repository with the appropriate layout for
+gbp buildpackage
+, with three branches:
+master
+(where the Debian development will happen),
+pristine-tar
+used by the
+pristine-tar
+tool during the package build process to recreate the original tarball,
+and
+upstream
+, which will contain the upstream source.
+To clone and follow every branch of a git repository.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the package is already in the Debian archive, you can use the
+``debcheckout`` command with its ``--git-track='*'`` option.
+
+To update the ``upstream``, ``master`` and ``pristine-tar`` branches at
+once, use the ``gbp pull``.
+
+To track extra upstream branches, simply check them out.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With recent versions of git, the remote branch will be automatically
+tracked when running ``git`` checkout. For example, when a
+``pristine-tar`` branch is available upstream and not yet tracked
+locally, the command ``git checkout`` ``pristine-tar`` will implicitly
+run the command ``git branch`` ``-t pristine-tar origin/pristine-tar``.
+
+To create a pristine-tar branch when it is missing.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See the `documentation of
+git-buildpackage <http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.import.html>`__
+for details. Use a similar command for any other missing branch.
+
+::
+
+ git checkout --orphan upstream
+ git rm -rf .
+ git commit --allow-empty -m 'Initial upstream branch.'
+ git checkout -f master
+
+Pushing to git.debian.org, creating a new bare repository on Alitoh.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before pushing to git.debian.org for the first time, an empty repository
+needs to be created there. To do this connect to ``git.debian.org``,
+enter the\ ``/git/debian-med`` directory, and run
+the\ `` ./setup-repository`` script.
+
+Run it similar to:
+
+::
+
+ ssh git.debian.org
+ cd /git/debian-med
+ ./setup-repository <pkg> 'Packaging of <pkg> in Debian'
+
+This will create an empty, bare, shared Git repository and setup some
+hooks. Each package is kept in its own Git repository. Now, on your
+local machine add the alioth repository as a remote:
+
+::
+
+ git remote add origin git+ssh://git.debian.org/git/debian-med/<pkg>.git
+
+This is done automatically after cloning a repository, for instance with
+`debcheckout <#debcheckout-git-track>`__. The default remote branch is
+called “origin”.
+
+To change the default branch.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the Debian work is not on the ``master`` branch, change the default
+branch by editing the ``HEAD`` file in the bare repository on Alioth,
+and replace ``master`` by the name of the new default branch. For a
+branch called ``debian/unstable`` the contents of the file will
+``refs/heads/debian/unstable``.
+
+To push the package.
+~~~~~~~~~~~~~~~~~~~~
+
+(make sure you've added the alioth remote!), do the following:
+``git push origin
+ master``. For the first push, it's necessary to specify
+``origin master``. The next time you will push, a ``git push`` will
+suffice. Or use the ``--set-upstream`` option, helps future use of git
+pull.
+
+::
+
+ git push --set-upstream
+
+To push all your work
+~~~~~~~~~~~~~~~~~~~~~
+
+Be sure to also do a run ``git push`` with ``--all``, and one with
+``--tags`` if you created new tags.
+
+::
+
+ git push --all --set-upstream
+ git push --tags
+
+To tag a release
+~~~~~~~~~~~~~~~~
+
+``git tag debian/x.y-z``. You can also easily retroactively make tags:
+``git tag debian/x.y-z <commit hash>``. Remember to ``git push --tags``.
+
+If upstream manages his sources with Git.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following makefile script can help producing a version number when
+no Git tag is available:
+
+::
+
+ SOURCEPKG=$(shell dpkg-parsechangelog | sed -n 's/^Source: \(.*\)/\1/p')
+ UPSTREAM=$(shell dpkg-parsechangelog | sed -n 's/^Version: \(.*\)-[^-]*/\1/p')
+ SHA1=$(lastword $(subst ~g, ,$(UPSTREAM)))
+ ORIG=${SOURCEPKG}_${UPSTREAM}.orig.tar.gz
+
+ describe-current-version:
+ git describe --tags upstream | sed 's,^release-,,;s,-,+,;s,-,~,;'
+
+ get-orig-source:
+ git archive --format=tar $(SHA1) | gzip -9 > ../$(ORIG)
+
+To make ``gbp buildpackage`` build the package with ``pdebuild``.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add the following to the configuration file ``~/.gbp.conf`` or
+``debian/gbp.conf``:
+
+::
+
+ [DEFAULT]
+ builder = ~/bin/git-pbuilder
+
+With this configuration file you're specifying that ``gbp buildpackage``
+will use ``~/bin/git-pbuilder`` as the builder script. This is an
+example script you can use:
+
+::
+
+ #!/bin/sh
+ set -e
+
+ pdebuild --pbuilder cowbuilder --debbuildopts "-i\.git -I.git $*"
+ rm ../*_source.changes
+
+This will build the package inside the default cowbuilder chroot, while
+passing any more parameters directly do ``dpkg-buildpackage``.
+
+Migration of a source package from Subversion to Git.
+-----------------------------------------------------
+
+For packages were we set the ``mergeWithUpstream`` 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.
+
+- Start the conversion as explained in the
+ `Alioth/Git <http://wiki.debian.org/Alioth/Git#ConvertaSVNAliothrepositorytoGit>`__
+ page of the Debian wiki. To be consistent with a later usage of
+ ``gbp buildpackage``, it is preferable to prefix the tag names
+ “debian”. During this conversion, you can take advantage of the file
+ ``/trunk/helper-scripts/debian-med-authors`` in the Subversion
+ repository, and expand it if necessary.
+
+ ::
+
+ svn checkout svn+ssh://svn.debian.org/svn/debian-med/trunk/helper-scripts/debian-med-authors
+
+ You can also use the script
+ ``/trunk/helper-scripts/convert_svn_2_git`` that tries to implement
+ the `Wiki
+ page <http://wiki.debian.org/Alioth/Git#ConvertaSVNAliothrepositorytoGit>`__
+ but be aware that the tags from SVN are lost (enhancements / fixes
+ are welcome).
+
+- Import of the upstream original tarballs that you find relevant, for
+ instance the ones that were part of a stable release). When this
+ paragraph was written, it was necessary to follow special instruction
+ detailed in `bug
+ 471560 <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=471560>`__.
+
+- Upload to git.debian.org/git/debian-med and set up the hooks and
+ other meta-data as explained in the
+ `Alioth/Git <http://wiki.debian.org/Alioth/Git>`__ page of the Debian
+ wiki.
+
+- Document in the Subversion repository that the package has been
+ transferred elsewhere, for instance with a file named
+ ``README.status`` containing the new VCS URL.
+
+- Delete the package in the Subversion repository after its VCS URL in
+ Stable has been updated by the next release.
+
+It is also possible to prepare a Git repository containing some of the
+package's history using the command ``gbp import-dscs --debsnap`` from
+the helper toolkit ``gbp buildpackage``. This will download all the
+versions of a package available in
+`snapshots.debian.org <http://snapshot.debian.org>`__ and create tags
+for each of them. Note that as this paragraph is written, the tool is
+not aware that *backports* should be a different branch
+
+Updating a source package managed with Git
+------------------------------------------
+
+Most source packages maintained as Git repositories in Debian Med are
+using the ``gbp buildpackage`` helper toolkit. In doubt, try this one
+first.
+
+``gbp buildpackage``'s command ``gbp import-orig`` makes it easy to
+update of the *upstream* branch using upstream releases distributed as a
+compressed archive, and to merge these changes in the *master* branch.
+Its option ``--pristine-tar`` is useful for stabilizing the MD5 sum of
+the “\ ``orig.tar.gz``\ ” produced when building a source package from
+the repository alone (not doing so results in archive rejection of
+package updates). With recent versions of ``gbp buildpackage``, it is
+often unnecessary to rename the freshly downloaded original upstream
+archive.
+
+If you do not use ``gbp buildpackage``, please use ``pristine-tar``
+anyway to register the compressed archives that you upload to Debian as
+original upstream sources (the ``orig.tar.{gz|bz2|xz}`` file), with a
+command such as the following, where ``tarball`` is a path to the
+archive file and ``tag`` is the upstream release tag for that archive
+(as a fallback, if you created the tarball from a given branch, use the
+name of the branch).
+
+::
+
+ pristine-tar commit tarball tag
+
+Commit messages are sent to our commit mailing list with the
+`git-multimail <https://github.com/mhagger/git-multimail/>`__ tool. To
+avoid sending too many messages, consider setting the option
+``multimailhook.maxCommitEmails`` to a low value, for instance 20; the
+default is 500…
+
+Packaging
+=========
+
+Newcomer guidelines for building proper Debian packages
+-------------------------------------------------------
+
+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
+`Debian New Maintainers'
+Guide <http://www.debian.org/doc/manuals/maint-guide/>`__.
+
+See also the `package
+template <http://anonscm.debian.org/viewvc/debian-med/trunk/package_template/>`__
+in our Subversion repository.
+
+There is also the option of joining the `Mentoring if the
+Month <https://wiki.debian.org/DebianMed/MoM>`__ as student to get a
+personal training how to start working inside the Debian Med team.
+
+Announcing intent to package
+----------------------------
+
+If you intent to work on a Debian package you should follow the `normal
+Debian rules <http://www.debian.org/devel/wnpp/#l1>`__ and file a WNPP
+bug report.
+
+It is a good idea to keep the Debian Med mailing list
+debian-med at lists.debian.org `in
+CC <http://www.debian.org/Bugs/Reporting#xcc>`__ and to set it as the
+owner of the ITP to keep your co-workers informed. This will ensure that
+we notice if for some reason the package has not been uploaded.
+
+In addition, please add the package to the “task” file where it fits the
+best, and document your ITP number using the ``WNPP`` field name.
+
+Backports
+---------
+
+Debian offers `backports <http://backports.debian.org>`__ to provide
+up-to-date software for users of the official stable releases. Backports
+of Debian Med packages should be kept as branches in our
+`Git <#git-repository-structures>`__ repositories. The branch should be
+named using the release code names. As an example, the backports branch
+for Debian 8 ("jessie") should be named ``debian/jessie-backports``, in
+accordance with `DEP-14 <http://dep.debian.net/deps/dep14/>`__.
+
+In Git, preparing a backport can be as simple as:
+
+::
+
+ git checkout -b debian/jessie-backports
+ dch --bpo
+
+
+And then building the package using a Stable chroot after making any
+necessary adjustments to the packaging. See the `wiki on
+backports <https://wiki.debian.org/BuildingFormalBackports>`__ and the
+`main backports website <http://backports.debian.org>`__ for more
+detailed instructions.
+
+When preparing subsequent versions of a backport, the changelog should
+include all the changes since the previous backported version. You will
+want to make sure you set up your cloned repository to use
+``dpkg-mergechangelogs`` (from the ``dpkg-dev`` package) to avoid
+getting unnecessary merge conflicts. See its manpage section
+"Integration with Git" for how to set that up.
+
+::
+
+ git checkout debian/jessie-backports
+ git merge debian/unstable (or master)
+
+
+Now, you can try building against a Stable chroot.
+
+PPA for Ubuntu
+--------------
+
+Debian Med operates a `Personal Package
+Archive <https://launchpad.net/~debian-med/+archive/ppa>`__ (PPA) on
+Launchpad, where packages are backported for Ubuntu. There is currently
+no team policy on what to build.
+
+Please keep in mind issues like the possibility to upgrade to the next
+Ubuntu stable release. Packages that are backports can be made `inferior
+in version by using a
+tilde <http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version>`__.
+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: ``2.12.0-1~natty1`` (backport in PPA) <
+``2.12.0-1`` (from Debian in Ubuntu) < ``2.12.0-1natty1`` (in PPA,
+containing additions) < ``2.12.0-2`` (from Debian in Ubuntu).
+
+Packages sent to this PPA may be kept as branches in our repositories.
+
+Lintian checks are adapted to Ubuntu by setting the environment as
+follows: ``LINTIAN_PROFILE=ubuntu``.
+
+Debian unstable chroot on Ubuntu
+--------------------------------
+
+cowbuilder-dist sid create cowbuilder-dist sid login
+
+Derivatives working together with Debian Med
+--------------------------------------------
+
+Debian Med is proud that derivatives (like for instance
+`BioLinux <http://nebc.nerc.ac.uk/tools/bio-linux>`__) are profiting
+from our work inside Debian and we try to establish strong connections
+to these derivatives. With BioLinux the connection is as strong that a
+common workflow was created where BioLinux developers are injecting
+their packaging straight into the Debian Med version control system. To
+make sure that there will be no conflicts with the Debian revisions some
+attention should be payed to the revision numbering. If the derivative
+is creating a new package (either from scratch or an upgraded version)
+it should get the version
+``<upstreamversion>-0<derivativename><derivativerevision>`` (which is
+the versioning scheme usually used by Ubuntu).
+
+R packages
+----------
+
+`GNU R <http://packages.debian.org/r-base-core>`__ 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 ``r-base-dev``, this can be acheived by adding the
+substitution variable ``${R:Depends}`` in the *Depends* field of the
+binary package.
+
+Tasks
+=====
+
+The Debian Med `Debian Pure
+Blend <http://blends.alioth.debian.org/blends>`__ is organised by
+`tasks <http://debian-med.alioth.debian.org/tasks/index>`__, that group
+packages around broad themes such as `medical
+imaging <http://debian-med.alioth.debian.org/tasks/imaging>`__ for
+instance. The tasks list programs that are already packaged in Debian as
+well as packages in preparation.
+
+The tasks files are not hosted in the Debian Med repositories, but in
+the Debian Blends repository. Nevertheless, all members of the Debian
+Med project on the Alioth forge have write access to the Blends
+subversion repository. You can easily check out its sources with the
+command ``debcheckout -a debian-med``.
+
+The syntax of the tasks files is very similar to Debian control files,
+and described in the `Debian Blends
+website <http://blends.alioth.debian.org/blends/ch-sentinel.en.html>`__.
+
+Policy
+======
+
+``debian/control``
+------------------
+
+1. **Section.**
+
+ Should be “science” for the source package.
+
+2. **Priority.**
+
+ Should be “optional” unless forbidden by the Debian policy (`see
+ §2.5 <http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities>`__).
+ Packages of priority “extra” are excluded from some QA tests.
+
+3. **Maintainer.**
+
+ Maintainer should be
+ ``Debian Med Packaging Team debian-med-packaging at lists.alioth.debian.org``.
+ Please subscribe to this list if you list yourself in the
+ ``Uploaders:`` field of one of Debian Med's packages. You can refer
+ to the `QA
+ page <http://qa.debian.org/developer.php?login=debian-med-packaging@lists.alioth.debian.org>`__
+ corresponding to this email to gather information about the packages.
+
+4. **Uploaders.**
+
+ Please add yourself as an uploader when you have a significant
+ interest in a package. Being Uploader means that you are expected to
+ answer to the bug reports. For more occasional works, you can do a
+ `team
+ upload <http://www.debian.org/doc/developers-reference/pkgs#nmu-team-upload>`__.
+
+5. **Standards-Version.**
+
+ 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.
+
+6. **Homepage.**
+
+ should be documented whenever possible
+
+7. **Vcs-Svn: and Vcs-Browser:.**
+
+ Please use the following templates, and refer to the Debian Policy
+ `§ 5.6.26 <http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-VCS-fields>`__
+ for details:
+
+ ::
+
+ Vcs-Browser: http://anonscm.debian.org/viewvc/debian-med/trunk/packages/<package>/trunk/
+ Vcs-Svn: svn://anonscm.debian.org/debian-med/trunk/packages/<package>/trunk/
+
+ or
+
+ ::
+
+ Vcs-Browser: http://anonscm.debian.org/cgit/debian-med/<package>.git
+ Vcs-Git: git://anonscm.debian.org/debian-med/<package>.git
+
+8. **Testsuite: autopkgtest.**
+
+ Field and value to declare that a testsuite compatible with
+ `autopkgtest <http://dep.debian.net/deps/dep8/>`__ is available. Such
+ testsuite can be executed via the ``adt-run`` command from the
+ autopkgtest package or the ``sadt`` command from the devscripts
+ package. Note that since ``dpkg`` version 1.17.6, the *XS-* prefix is
+ not necessary anymore for this field.
+
+It is a very good idea to use ``Config::Model`` to unify the formatting
+of ``debian/control``. To do so make sure you have installed
+
+``apt-get``
+`` install cme libconfig-model-dpkg-perl libconfig-model-itself-perl``
+
+and than you can simply call
+
+``cme`` `` fix dpkg-control``
+
+to get a properly formated, sanity checked ``debian/control`` file.
+Please note that sometimes you need to call this more than once.
+
+``debian/copyright``
+--------------------
+
+We use the `machine-readable
+format <http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/>`__
+for the ``debian/copyright`` file. The ``Source`` field does not need to
+contain the full URL to the particular version that is being packaged,
+since this can be determined by the ``uscan`` program with the
+``debian/watch`` file (but note that some packagers use it as a bookmark
+to record when was the last copyright check). Please list yourself in
+the ``Files: debian/*`` section if you think that your contributions are
+not trivial and therefore subjected to copyright. Please chose a license
+that is compatible with the program you package. You can also use “same
+as if it were in the public domain” or “same as the packaged program
+itself”.
+
+To create some reasonable skeleton for a ``debian/copyright`` file you
+can try the following:
+
+::
+
+ sudo apt-get install devscripts cdbs
+ licensecheck --copyright -r `find -type f` | /usr/lib/cdbs/licensecheck2dep5 > debian/copyright
+
+To verify the correct syntax of the ``debian/copyright`` file you can
+use:
+
+::
+
+ config-edit -application dpkg-copyright -ui none
+
+or
+
+::
+
+ cme fix dpkg-copyright
+
+from package ``libconfig-model-dpkg-perl`` (see above).
+
+``debian/changelog``
+--------------------
+
+Packages hosted in our Subversion repository, that have been modified
+but not uploaded must use ``UNRELEASED`` as a distribution name. This
+can be done automatically by declaring
+``DEBCHANGE_RELEASE_HEURISTIC=changelog`` in ``~/.devscripts`` and using
+``dch``.
+
+``debian/upstream``
+-------------------
+
+We use the `bibliographic
+information <http://wiki.debian.org/UpstreamMetadata#Fields>`__ which
+should be stored in the file ``debian/upstream``. The purpose of
+specifying this is to enhance the contact to upstream which thus gets an
+extra reward of their work if their citations show up on pages inside
+the Debian domain and if users more popularly are asked to cite upstream
+when working with the program in question.
+
+``debian/gbp.conf``
+-------------------
+
+Include this file to document the layout of the repository. Packages
+managed with ``gbp buildpackage`` may omit default values.
+
+::
+
+ [DEFAULT]
+ # The default name for the upstream branch is "upstream".
+ # Change it if the name is different (for instance, "master").
+ upstream-branch = upstream
+ # The default name for the Debian branch is "master".
+ # Change it if the name is different (for instance, "debian/unstable").
+ debian-branch = master
+ # gbp import-orig uses the following names for the upstream tags.
+ # Change the value if you are not using gbp import-orig
+ upstream-tag = upstream/%(version)s
+ # Always use pristine-tar.
+ pristine-tar = True
+
+``debian/README.source``
+------------------------
+
+This file is recommended by the Policy
+(`§ 4.14 <http://www.debian.org/doc/debian-policy/ch-source.html#s-readmesource>`__)
+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,…
+
+``debian/README.test``
+----------------------
+
+This file was (`recommended by the Security
+team <http://lists.debian.org/debian-devel-announce/2011/01/msg00006.html>`__)
+for describing to others than the regular maintainer how the package's
+functionality can properly be tested.
+
+``debian/source/format``
+------------------------
+
+This file sould contain “``3.0 (quilt)``” in order to use this source
+format. Other formats should be avoided unless they bring a specific
+advantage.
+
+``debian/source/options``
+-------------------------
+
+For packages not using `quilt <#quilt>`__ patches, for example when
+committing changes directly to the Debian branch, this file should
+contain “``single-debian-patch``” in order to emulate the ``1.0``
+format. This is better than using the ``1.0`` format directly because
+the ``3.0
+ (quilt)`` format brings other advantages, in particular
+the conservation of file permissions in the ``debian`` directory.
+
+Debhelper
+---------
+
+Debhelper uses compatibility levels to control the behaviour of its
+commands. We currently recommend to use the level *9* which is available
+in current *Stable* (Wheezy) and backported to *Oldstable*. However,
+there is no urgent need to touch packages only because it has an older
+Debhelper version.
+
+It is strongly recommended to use the short *dh* notation in
+``debian/rules`` files which makes code factorisation very simple and
+easy to understand the packaging for other members of the team. Even
+complex packaging becomes quite transparent this way.
+
+CDBS
+----
+
+Before the short *dh* notation of debhelper existed CDBS was the only
+way to factorise code in ``debian/rules`` files. We would like to
+standardise on *dh* when both provide similar comfort. Please give it
+priority for new packages. It is also possible to switch to *dh* for
+existing packages, but this is entirely at the packagers discretion.
+
+It is technically possible to build CDBS packages using Debhelper
+without the ``debian/compat`` file. Please do not, and always include
+such a file according to the above guidelines.
+
+Version control systems
+-----------------------
+
+We are currently using two different version control systems, Subversion
+and Git.
+
+Source package stored in a Subversion repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We often use the ``mergeWithUpstream`` workflow. In that case, please
+keep all the modifications in the ``debian`` directory, and use the
+``-o`` option of ``svn-buildpackage``, as in the following example:
+``svn-inject
+ -o package.dsc svn+ssh://svn.debian.org/svn/debian-med/trunk/packages/``.
+
+Source package stored in a Git repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Git repositories should be stored in the ``/git/debian-med`` directory
+on Alioth and created with the
+```setup-repository`` <#create-git-repository-on-alioth>`__ script
+available there. There, they must give write access to the
+``debian-med`` Alioth group and all the Debian Developers, with
+appropriate Unix permissions (including SGID bit on directories) and
+ACLs. See ``/git/debian-med`` itself as an example. ``setup-repository``
+does this automatically.
+
+Git repositories managed with a helper tool should announce it. For
+instance, to show that ``gbp buildpackage`` is used, the package can
+contain a configuration file in ``debian/gbp.conf``.
+
+Tags
+~~~~
+
+Tags indicate the revision corresponding to uploaded packages. For
+Subversion, the version number is used, and for Git, ``debian/`` is
+added before the version number. In the Subversion repository, older
+tags may be deleted to save space.
+
+New package
+-----------
+
+Try to inject a new package only after successfully building it with
+``dpkg-buildpackage`` (or any wrapper around it). Use a file like
+``debian/DRAFT`` to mention when the package is a draft.
+
+The Debian Med Blend tasks
+--------------------------
+
+Once you injected a new package please make sure that it is mentioned in
+the appropriate `tasks <#tasks>`__ file in the SVN source of the
+debian-med Blend package. Some team members watch the changes in the
+Debian Med packaging pool but it helps if the maintainer of a new
+package verifies that everything is in the right place.
+
+Building and tagging the packages
+---------------------------------
+
+We prefer that uploaded packages are built in a chroot, to provide
+similar build environment to the whole team. After upload, please
+`tag <#vcs-tags>`__ the `Suvbersion <#svn-tag-release>`__ or
+`Git <#git-tag-release>`__ repository.
+
+Handling patches
+----------------
+
+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 ``1.0`` source format and in a monolithic patch if you use the
+``3.0 (quilt)`` format. To better organise the patches and group the by
+function, please use a patch handling system which keeps patches under
+the ``debian/patches`` directory.
+
+The ``3.0 (quilt)`` Dpkg source format provides its own patch system.
+Apart from this, the most popular is ``quilt``. *simple-patchsys*, from
+the CDBS package, is deprecated since version ``0.4.85``. ``dpatch`` has
+been popular as well, but is not compatible with the ``3.0 (quilt)``
+source format and is `planned to be removed
+2017 <http://lists.debian.org/878vqt6was.fsf@luthien.mhp>`__. Please
+don't use any other patch system in Debian Med, unless absolutely
+necessary.
+
+Using ``quilt``
+~~~~~~~~~~~~~~~
+
+Using quilt is rather easy.
+
+First, make sure you have correctly setup quilt: open ``.quiltrc`` in
+your home directory (create it if you don't have one), and make sure it
+looks like this:
+
+ ::
+
+ QUILT_DIFF_ARGS="--no-timestamps --no-index"
+ QUILT_REFRESH_ARGS="--no-timestamps --no-index"
+ QUILT_PATCHES="debian/patches"
+
+After this, you're ready to start working with quilt. See also the
+instructions in the `New Maintainer's
+Guide <http://www.debian.org/doc/manuals/maint-guide/modify#quiltrc>`__.
+
+Creating a patch
+^^^^^^^^^^^^^^^^
+
+To create a patch, use the ``new`` command. Run:
+
+ ``
+ quilt new <patch_name>.patch
+ ``
+
+This will create (if it doesn't exist yet) a ``debian/patches/series``
+file, which contains all the patches to be applied by quilt. Moreover,
+the new patch is also the topmost (the currently applied).
+
+Now start editing files, with:
+
+ ``
+ quilt edit <file>
+ ``
+
+and repeat the process for each file the patch is involved with. At the
+end, run
+
+ ``
+ quilt refresh
+ ``
+
+This will compare the noted state of the edited files with the current
+state, and will produce a patch in ``debian/patches``. Remember: the
+patch is currently applied (you can check this with ``quilt applied``).
+
+Make sure to write the patch header and use the `DEP3
+format <http://dep.debian.net/deps/dep3/>`__:
+
+ ``
+ quilt header -e --dep3
+ ``
+
+Applying and unapplying patches
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Just two easy commands to do the job:
+
+- ``quilt pop`` will unapply the topmost patch.
+
+- ``quilt push`` will apply the next patch in debian/patches/series.
+
+You can just add a "-a" flag to the commands above, to respectively
+apply/unapply all patches in the series.
+
+ **Tip**
+
+ You can check which patches are applied/unapplied with,
+ respectively, ``quilt applied`` and ``quilt unapplied``.
+
+Editing patches
+^^^^^^^^^^^^^^^
+
+To edit a patch, first make it the topmost:
+
+ ``
+ quilt push <patch_name>
+ ``
+
+If the patch is already applied, but is not the topmost, run
+``quilt pop`` until it becomes the currently applied one.
+
+You can now run ``quilt edit`` on the files you want to change, and,
+when you're done, ``quilt
+ refresh``.
+
+Renaming patches
+^^^^^^^^^^^^^^^^
+
+Sometimes it's useful to rename a patch. Without any hassle, do:
+
+ ``
+ quilt rename -P <old_name>.patch
+ <new_name>.patch
+ ``
+
+Other commands
+^^^^^^^^^^^^^^
+
+Please see ``man 1 quilt`` to have a comprehensive list of commands.
+
+FAQ
+===
+
+What to do if a large package does not build on a specific autobuilder architecture?
+------------------------------------------------------------------------------------
+
+Some of our target packages are large regarding memory consumption or
+requiring more computing power to build on not so powerful
+architectures. Since the Debian autobuilder infrastructure consists of
+differently equiped hosts which are picked at random it might help to
+ask at
+
+ <arch>@buildd.debian.org
+
+to blacklist the weaker candidates.
+
+.. |image0| image:: /img/debian-med.jpg
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/policy.git
More information about the debian-med-commit
mailing list