[med-svn] [Git][med-team/policy][master] switch to ReStructuredText from docbook
Michael R. Crusoe
gitlab at salsa.debian.org
Sun Mar 10 08:47:11 GMT 2019
Michael R. Crusoe pushed to branch master at Debian Med / policy
Commits:
1cb4640d by Michael R. Crusoe at 2019-03-10T08:46:09Z
switch to ReStructuredText from docbook
- - - - -
5 changed files:
- Makefile
- policy.html
- + policy.rst
- − policy.xml
- − policy_short.rst
Changes:
=====================================
Makefile
=====================================
@@ -4,16 +4,11 @@ PUBLISHDIR=/home/groups/debian-med/htdocs/docs
all: policy
policy:
- xsltproc --output policy.html \
- /usr/share/xml/docbook/stylesheet/docbook-xsl/xhtml/docbook.xsl \
- policy.xml 2>/dev/null
-
-rst2html:
- pandoc -t html -o policy_short.html policy_short.rst 2>/dev/null
+ rst2html policy.rst > policy.html
clean:
rm -f policy*.html
install-deps:
- sudo apt-get install xsltproc docbook-xsl pandoc
+ sudo apt-get install python3-docutils
=====================================
policy.html
=====================================
The diff for this file was not included because it is too large.
=====================================
policy.rst
=====================================
@@ -0,0 +1,1043 @@
+|debian-med-logo|
+
+.. contents:: Table of Contents
+
+Introduction
+============
+
+Debian Med is a “`Debian Pure
+Blend <https://blends.debian.org/blends>`__” with the aim to develop
+Debian into an operating system that is particularly well tailored 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.
+
+.. _contribute:
+
+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 <https://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 <https://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 `page on
+Salsa <https://salsa.debian.org/med-team/>`__, or directly follow this
+`link <https://salsa.debian.org/groups/med-team/-/group_members/request_access>`__.
+Remember that you must have an account on Salsa.debian.org before
+requesting membership (see
+`here <https://salsa.debian.org/users/sign_in>`__ to request an account
+on Salsa.debian.org).
+
+.. _readings:
+
+Essential readings
+------------------
+
+- The `Debian Policy <https://www.debian.org/doc/debian-policy/>`__:
+ packages must conform to it.
+
+- The `Developers
+ Reference <https://www.debian.org/doc/developers-reference/>`__:
+ details best packaging practices.
+
+- The `New Maintainer's
+ Guide <https://www.debian.org/doc/maint-guide/>`__: puts a bit of the
+ two above in practice.
+
+- The `Debian Med
+ Policy <https://med-team.pages.debian.net/policy.html>`__ (this
+ document): explains how the work is organised in our team.
+
+.. _meta:
+
+Contributing to this Policy
+---------------------------
+
+This policy is itself maintained in Git and all team members have write
+access to its repository.
+
+::
+
+ git clone git at salsa.debian.org:med-team/policy.git
+ Make changes to policy.rst commit and push.
+ Publish using the following command:
+ make publish
+
+
+Repositories
+============
+
+We use Git repositories, hosted by Debian. You can have a look at each
+repository through `Salsa's web
+interfaces <https://salsa.debian.org/groups/med-team/>`__.
+
+.. _source:
+
+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 <https://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 Salsa:
+
+ ::
+
+ gbp clone <username> git at salsa.debian.org:med-team/<package>.git
+
+ 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 at salsa.debian.org:med-team/<package>.git
+
+- For read-only access with ``debcheckout``, remove the ``--user``
+ option. With ``gbp clone``, use an anonymous URL like the following:
+
+ ::
+
+ gbp clone https://salsa.debian.org/med-team/<package>.git
+
+.. _git-repository-structures:
+
+Common Git repository structures
+--------------------------------
+
+.. _git-buildpackage:
+
+``gbp buildpackage``
+~~~~~~~~~~~~~~~~~~~~
+
+Most of our packages using Git and stored on Salsa 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``.
+
+.. _git-without-tarball:
+
+Social Git
+~~~~~~~~~~
+
+For some projects, like the ones hosted on
+`GitHub <https://www.github.com>`__ or
+`GitLab <https://www.gitlab.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.
+
+.. _git-branches:
+
+Other branches
+~~~~~~~~~~~~~~
+
+Changes uploaded to other distributions than ``unstable`` can be stored
+in other branches, named for instance ``experimental``, ``stable``, etc.
+
+Git tips
+--------
+
+.. _git-options-devscripts:
+
+Set the devscripts variables ``DEBEMAIL`` and ``DEBFULLNAME``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``debcheckout`` will then set ``git``'s options ``user.email`` and
+``user.name`` accordingly.
+
+.. _debcheckout-sets-git-options:
+
+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"
+
+.. _new-repository-with-gbp:
+
+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. In the Gitlab interface of
+`Salsa <https://salsa.debian.org/med-team/>`__ you can seek for software
+packaged 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
+ git clone https://salsa.debian.org/med-team/community/package_template.git /tmp/package_template
+ mv /tmp/package_template/debian . ; rm -rf /tmp/package_template
+
+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.
+.. _debcheckout-git-track:
+
+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``.
+
+.. _git-track-new-branches:
+
+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``.
+
+.. _git-missing-pristine-tar:
+
+To create a pristine-tar branch when it is missing.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See the `documentation of
+git-buildpackage <https://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
+
+.. _create-git-repository-on-salsa:
+
+Creating a new repository on Salsa
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before pushing to salsa.debian.org for the first time, an empty
+repository needs to be created there in the Gitlab interface.
+
+Each package is kept in its own Git repository. Now, on your local
+machine add the salsa repository as a remote:
+
+::
+
+ git remote add origin git at salsa.debian.org:med-team/<pkg>.git
+
+.. _git-change-default-branch:
+
+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 Salsa, 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``.
+
+.. _push-package-to-salsa:
+
+To push the package.
+~~~~~~~~~~~~~~~~~~~~
+
+(make sure you've added the salsa 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
+
+.. _git-push-all-tags:
+
+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
+
+.. _git-tag-release:
+
+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``.
+
+.. _git-debian-version-from-commit:
+
+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)
+
+.. _git-pbuilder:
+
+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
+
+ pristine-tar = True
+
+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``.
+
+.. _updating-git-package:
+
+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
+=========
+
+.. _packagingguidelines:
+
+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 <https://www.debian.org/doc/manuals/maint-guide/>`__.
+
+See also the `package
+template <https://salsa.debian.org/med-team/community/package_template>`__
+on Salsa.
+
+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.
+
+.. _itp:
+
+Announcing intent to package
+----------------------------
+
+If you intent to work on a Debian package you should follow the `normal
+Debian rules <https://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 <https://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 <https://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 9 ("stretch") should be named ``debian/stretch-backports``,
+in accordance with `DEP-14 <http://dep.debian.net/deps/dep14/>`__. If
+you are developing on Stable, make sure to get the ``devscripts``
+package from stretch-backports for ``dch --bpo`` to set the version
+properly.
+
+In Git, preparing a backport can be as simple as:
+
+::
+
+ git checkout debian/VESIONTAG
+ git checkout -b debian/stretch-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 <https://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/stretch-backports
+ git merge debian/TO_BE_BACKPORTED_VERSION
+ dch --bpo
+
+
+Now, you can try building against a Stable chroot.
+
+.. _ppa:
+
+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.
+
+Because the space in the PPA is currently limited (4.0 GiB), we keep in
+the PPA only packages for `still
+maintained <https://wiki.ubuntu.com/Releases>`__ LTS Ubuntu version.
+Packages targeting an older Ubuntu will be removed.
+
+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 <https://www.debian.org/doc/debian-policy/#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). Please follow the Ubuntu's
+`recommendations <https://help.launchpad.net/Packaging/PPA/BuildingASourcePackage#versioning>`__
+for versioning packages in PPA.
+
+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``.
+
+.. _sidonubuntu:
+
+Debian unstable chroot on Ubuntu
+--------------------------------
+
+cowbuilder-dist sid create cowbuilder-dist sid login
+
+.. _derivatives:
+
+Derivatives working together with Debian Med
+--------------------------------------------
+
+Debian Med is proud that derivatives (like for instance
+`Bio-Linux <http://environmentalomics.org/bio-linux/>`__) are profiting
+from our work inside Debian and we try to establish strong connections
+to these derivatives. With Bio-Linux the connection is as strong that a
+common workflow was created where Bio-Linux 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
+----------
+
+Debian R packages should be maintained within the `Debian R Packages
+Team <https://wiki.debian.org/Teams/r-pkg-team>`__.
+
+`GNU R <https://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 <https://blends.debian.org/blends>`__
+is organised by `tasks <https://blends.debian.org/med/tasks>`__, that
+group packages around broad themes such as `medical
+imaging <https://blends.debian.org/med/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 Salsa have write access to the Blends Git 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 <https://blends.debian.org/blends/ch08.html#edittasksfiles>`__.
+
+Policy
+======
+
+.. _debian-control:
+
+``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 <https://www.debian.org/doc/debian-policy/#priorities>`__).
+ Packages of priority “extra” are excluded from some QA tests.
+
+3. **Maintainer.**
+
+ Maintainer should be
+ ``Debian Med Packaging Team debian-med-packaging at alioth-lists.debian.net``.
+ 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 <https://qa.debian.org/developer.php?login=debian-med-packaging@alioth-lists.debian.net>`__
+ 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 <https://www.debian.org/doc/manuals/developers-reference/pkgs.html#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-Git: and Vcs-Browser:.**
+
+ Please use the following templates, and refer to the Debian Policy
+ `§ 5.6.26 <https://www.debian.org/doc/debian-policy/#version-control-system-vcs-fields>`__
+ for details:
+
+ ::
+
+ Vcs-Browser: https://salsa.debian.org/med-team/<package>
+ Vcs-Git: https://salsa.debian.org/med-team/<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``
+
+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. In case
+you want to use the cme GUI you also need to
+
+``apt-get`` ``install libconfig-model-tkui-perl``
+
+which enables you to do something like
+
+``cme`` ``edit dpkg``
+
+.. _debian-copyright:
+
+``debian/copyright``
+--------------------
+
+We use the `machine-readable
+format <https://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”.
+
+You can create a
+debian/copyright
+file from scratch using
+``cme`` ``update dpkg-copyright``
+
+Alternatively you can 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:
+
+::
+
+ cme check|fix|edit dpkg-copyright
+
+from package ``libconfig-model-dpkg-perl`` (see above).
+
+.. _debian-changelog:
+
+``debian/changelog``
+--------------------
+
+Packages hosted in our Git 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:
+
+``debian/upstream``
+-------------------
+
+We use the `bibliographic
+information <https://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.
+
+A new development are registries of research software (e.g. SciCrunch's
+RRID, bio.tools, OMICtools). The metadata allows for references to
+publications and entries in these registries alike.
+
+.. _debian-gbp.conf:
+
+``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:
+
+``debian/README.source``
+------------------------
+
+This file is recommended by the Policy
+(`§ 4.14 <https://www.debian.org/doc/debian-policy/#source-package-handling-debian-readme-source>`__)
+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:
+
+``debian/README.test``
+----------------------
+
+This file was (`recommended by the Security
+team <https://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:
+
+``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-option:
+
+``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 *10* which is
+available in current *Stable* 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.
+
+.. _vcs:
+
+Version control systems
+-----------------------
+
+.. _vcs-git:
+
+Source package stored in a Git repository on Salsa
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Git repositories should be stored on
+`Salsa <https://salsa.debian.org/med-team/>`__.
+
+.. _vcs-tags:
+
+Tags
+~~~~
+
+Tags indicate the revision corresponding to uploaded packages. For a
+released package ``debian/`` is added before the package version number.
+
+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.
+
+.. _new-packages-in-tasks:
+
+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 Git 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:
+
+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 `Git <#git-tag-release>`__ repository.
+
+.. _patches:
+
+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.
+You can use it with the ``quilt`` command.
+
+.. _quilt:
+
+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 <https://www.debian.org/doc/manuals/maint-guide/modify.en.html#quiltrc>`__.
+
+.. _quilt-create:
+
+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``
+
+.. _quilt-apply:
+
+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``.
+
+.. _quilt-edit:
+
+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``.
+
+.. _quilt-rename:
+
+Renaming patches
+^^^^^^^^^^^^^^^^
+
+Sometimes it's useful to rename a patch. Without any hassle, do:
+
+ ``quilt rename -P <old_name>.patch <new_name>.patch``
+
+.. _quilt-other:
+
+Other commands
+^^^^^^^^^^^^^^
+
+Please see ``man 1 quilt`` to have a comprehensive list of commands.
+
+FAQ
+===
+
+.. _autobuilder:
+
+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.
+
+.. |debian-med-logo| image:: https://people.debian.org/~tille/debian-med/logos/med-06.jpg
+
=====================================
policy.xml deleted
=====================================
@@ -1,881 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<?xml-stylesheet type="text/xsl"
- href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
- "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
-<article xml:base="http://med-team.pages.debian.net/">
- <title>Debian Med Group Policy</title>
- <articleinfo>
- <authorgroup>
- <author>
- <firstname>Andreas</firstname>
- <surname>Tille</surname>
- <contrib>First review </contrib>
- <email>tille at debian.org</email>
- </author>
- <author>
- <firstname>David</firstname>
- <surname>Paleino</surname>
- <contrib>Initial writing </contrib>
- <email>d.paleino at gmail.com</email>
- </author>
- <author>
- <firstname>Charles</firstname>
- <surname>Plessy</surname>
- <contrib>Contributions in 2008 and 2011</contrib>
- <email>plessy at debian.org</email>
- </author>
- </authorgroup>
- <releaseinfo>
- $ policy.xml rev. @REV@ - @DATE@ (@AUTHOR@) $
- </releaseinfo>
- <releaseinfo>
- Source: https://salsa.debian.org/med-team/policy
- </releaseinfo>
- </articleinfo>
- <mediaobject>
- <objectinfo>
- <title>Debian Med Group</title>
- </objectinfo>
- <imageobject>
- <imagedata fileref="/img/debian-med.jpg" format="JPG" align="center" />
- </imageobject>
- </mediaobject>
- <sect1 id="introduction">
- <title>Introduction</title>
- <para>Debian Med is a <quote><ulink url="https://blends.debian.org/blends">Debian Pure Blend</ulink></quote>
- with the aim to develop Debian into an operating system that is particularly
- well tailored for the requirements for medical practice and research.</para>
- <para>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.</para>
- <para>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.</para>
- </sect1>
- <sect1 id="contribute">
- <title>How to Contribute</title>
- <para>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.</para>
- <para>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.</para>
- <para>We also dedicate some time to advertise it to the world via
- <ulink url="https://www.debian.org">www.debian.org</ulink>
- and to ease the integration of new members.</para>
- <para>Please contact us on <ulink url="mailto:debian-med at lists.debian.org">debian-med at lists.debian.org</ulink>
- if you want to help to make medical and biological software available
- to Debian users. Read the <link linkend="membership">Membership</link> section if you're
- interested in joining us.</para>
- <para>If you speak a language other than English, you can contribute
- rightaway with translations of package descriptions at
- <ulink url="https://ddtp.debian.net">ddtp.debian.net</ulink>.</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 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.</para>
- <sect2 id="membership">
- <title>Membership</title>
- <para>To request membership to this group, please go on our
- <ulink url="https://salsa.debian.org/med-team/">page on Salsa</ulink>,
- or directly follow this <ulink url="https://salsa.debian.org/groups/med-team/-/group_members/request_access">link</ulink>.
- Remember that you must have an account on Salsa.debian.org before requesting
- membership (see <ulink url="https://salsa.debian.org/users/sign_in">here</ulink>
- to request an account on Salsa.debian.org).</para>
- </sect2>
- <sect2 id="readings">
- <title>Essential readings</title>
- <itemizedlist>
- <listitem><para>The <ulink url="https://www.debian.org/doc/debian-policy/">Debian Policy</ulink>: packages must conform to it.</para></listitem>
- <listitem><para>The <ulink url="https://www.debian.org/doc/developers-reference/">Developers Reference</ulink>: details best packaging practices.</para></listitem>
- <listitem><para>The <ulink url="https://www.debian.org/doc/maint-guide/">New Maintainer's Guide</ulink>: puts a bit of the two above in practice.</para></listitem>
- <listitem><para>The <ulink url="https://med-team.pages.debian.net/policy.html">Debian Med Policy</ulink> (this document): explains how the work is organised in our team.</para></listitem>
- </itemizedlist>
- </sect2>
- <sect2 id="meta">
- <title>Contributing to this Policy</title>
- <para>
- This policy is itself maintained in Git and all team members have write access
- to its repository.
- <programlisting>
- <command>git clone git at salsa.debian.org:med-team/policy.git</command>
- Make changes to policy.xml commit and push.
- Publish using the following command:
- <command>make publish</command>
- </programlisting>
- </para>
- </sect2>
- </sect1>
- <sect1 id="repositories">
- <title>Repositories</title>
- <para>We use Git repositories, hosted
- by Debian. You can have a look at each repository through
- <ulink url="https://salsa.debian.org/groups/med-team/">Salsa's web interfaces</ulink>.</para>
- <sect2 id="source">
- <title>Give me the source!</title>
- <para>
- To check the sources of a package (referred as
- <emphasis><package></emphasis> below) in our repositories, use the
- <command>debcheckout</command> command, from the
- <ulink url="https://packages.debian.org/devscripts">devscripts</ulink>
- package.
- <itemizedlist>
- <listitem>
- <para>
- If you are a member of Debian Med or a Debian developer, with
- account name <emphasis><username></emphasis>, you have
- write permission.
- </para>
- <para>
- If the package is already in the archive:<programlisting>
-<command>debcheckout</command> <option>--user</option> <replaceable><username></replaceable> <option>--git-track <replaceable>'*'</replaceable></option> <replaceable><package></replaceable></programlisting>
- </para>
- <para>
- For draft packages that are only on Salsa:<programlisting>
-<command>gbp</command> <option>clone</option> <replaceable><username></replaceable> <replaceable>git at salsa.debian.org:med-team/<package>.git</replaceable></programlisting>
- </para>
- <para>
- For packages managed with Git, the option <option>--git-track</option>
- ensures that the clone has all the branches tracked. This is
- needed when using the <link linkend="git-buildpackage">gbp buildpackage</link>
- helper. Alternatively to <command>debcheckout</command>, the command
- <command>gbp clone</command> will also track the relevant branches:<programlisting>
-<command>gbp clone</command> <replaceable>git at salsa.debian.org:med-team/<package>.git</replaceable></programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- For read-only access with <command>debcheckout</command>, remove
- the <option>--user</option> option. With <command>gbp clone</command>,
- use an anonymous URL like the following:<programlisting>
-<command>gbp clone</command> <replaceable>https://salsa.debian.org/med-team/<package>.git</replaceable></programlisting>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="git-repository-structures">
- <title>Common Git repository structures</title>
- <sect3 id="git-buildpackage">
- <title><command>gbp buildpackage</command></title>
- <para>
- Most of our packages using Git and stored on Salsa are managed following
- the standard layout of the <command>gbp buildpackage</command> helper. The
- <literal>master</literal> branch contains the full source package.
- The <literal>upstream</literal> branch contains the upstream source,
- after repacking when necessary (non-free files, large convenience code
- copies, …). The <literal>pristine-tar</literal> contains the data
- necessary to recreate an original tarball from the repository with a
- reproducible checksum.
- </para>
- <para>
- Debian releases are tagged with names like
- <literal>debian/debianversion</literal> and upstream releases are
- tagged with names like <literal>upstream/upstreamversion</literal>.
- </para>
- </sect3>
- <sect3 id="git-without-tarball">
- <title>Social Git</title>
- <para>
- For some projects, like the ones hosted on <ulink
- url="https://www.github.com">GitHub</ulink> or <ulink
- url="https://www.gitlab.com">GitLab</ulink>, 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
- <link linkend="git-change-default-branch">default branch</link>, It must
- be indicated in the <link linkend="vcs-url">VCS URL</link> with the
- <option>-b</option> option.
- </para>
- <para>
- Even when you are not using <command>gbp buildpackage</command>,
- please include a <link linkend="debian-gbp.conf"><filename>debian/gbp.conf</filename></link>,
- to document the layout of the repository.
- </para>
- </sect3>
- <sect3 id="git-branches">
- <title>Other branches</title>
- <para>
- Changes uploaded to other distributions than <literal>unstable</literal> can be stored in other branches, named for instance <literal>experimental</literal>, <literal>stable</literal>, etc.
- </para>
- </sect3>
- </sect2>
-
- <sect2 id="git-tips">
- <title>Git tips</title>
- <sect3 id="git-options-devscripts">
- <title>Set the <package>devscripts</package> variables
- <varname>DEBEMAIL</varname> and <varname>DEBFULLNAME</varname></title>
- <para><command>debcheckout</command> will then set
- <command>git</command>'s options <varname>user.email</varname> and
- <varname>user.name</varname> accordingly.
- </para>
- </sect3>
- <sect3 id="debcheckout-sets-git-options">
- <title>Configure Git to commit using your packager name and address.</title>
- <para>The <option>--global</option> option is to say Git these are the default parameters for every Git repository you commit to,
- without it the settings will be per-repository only:</para>
- <para>
-<programlisting>
-<command>git config</command> <option><optional>--global</optional></option> <option>user.name "$DEBFULLNAME"</option>
-<command>git config</command> <option><optional>--global</optional></option> <option>user.email "$DEBEMAIL"</option></programlisting>
- </para>
- </sect3>
- <sect3 id="new-repository-with-gbp">
- <title>To create a new local git repository</title>
- <para>Before you create a new git repository you probably want to check whether your target project just exists.
- In the Gitlab interface of <ulink url="https://salsa.debian.org/med-team/">Salsa</ulink> you can seek
- for software packaged by the Debian Med team.
- </para>
- <para>When the upstream sources are distributed as compressed <command>tar</command> archives (<literal>tar.gz</literal>, …):<programlisting>
-<command>mkdir</command> <filename class="directory">package</filename>
-<command>cd</command> <filename class="directory">package</filename>
-<command>git init</command>
-<command>gbp import-orig</command> <option>--pristine-tar</option> <filename>/path/to/package_version.orig.tar.gz</filename>
-<command>git clone https://salsa.debian.org/med-team/community/package_template.git /tmp/package_template</command>
-<command>mv /tmp/package_template/debian . ; rm -rf /tmp/package_template</command></programlisting>
- </para>
- The above steps will create a repository with the appropriate layout for <command>gbp buildpackage</command>, with three branches:
- <literal>master</literal> (where the Debian development will happen),
- <literal>pristine-tar</literal> used by the <literal>pristine-tar</literal> tool during the package build process to recreate the original tarball,
- and <literal>upstream</literal>, which will contain the upstream source.
- </sect3>
- <sect3 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
- <command><option>--git-track='*'</option></command> option.
- </para>
- <para>To update the <literal>upstream</literal>, <literal>master</literal> and <literal>pristine-tar</literal> branches at once, use the <command>gbp pull</command>.</para>
- </sect3>
- <sect3 id="git-track-new-branches">
- <title>To track extra upstream 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. For example, when a <literal>pristine-tar</literal> branch is available upstream and not yet tracked locally, the command <command>git checkout</command> <option><replaceable>pristine-tar</replaceable></option> will implicitly run the command <command>git branch</command> <option>-t <replaceable>pristine-tar</replaceable> <replaceable>origin/pristine-tar</replaceable></option>.
- </para>
- </sect3>
- <sect3 id="git-missing-pristine-tar">
- <title>To create a pristine-tar branch when it is missing.</title>
- <para>
- See the <ulink url="https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.import.html">documentation of git-buildpackage</ulink>
- for details. Use a similar command for any other missing branch.
- <programlisting>
-<command>git checkout</command> <option>--orphan</option> <replaceable>upstream</replaceable>
-<command>git rm</command> <option>-rf</option> <replaceable>.</replaceable>
-<command>git commit</command> <option>--allow-empty</option> <option>-m</option> <replaceable>'Initial upstream branch.'</replaceable>
-<command>git checkout</command> <option>-f</option> <replaceable>master</replaceable>
-</programlisting>
- </para>
- </sect3>
- <sect3 id="create-git-repository-on-salsa">
- <title>Creating a new repository on Salsa</title>
- <para>Before pushing to salsa.debian.org for the first time, an empty repository needs to be created there in the Gitlab interface.
- </para><para>
- Each package is kept in its own Git repository.
- Now, on your local machine add the salsa repository as a remote:<programlisting>
-<command>git remote add</command> <literal>origin</literal> <filename class="directory">git at salsa.debian.org:med-team/<pkg>.git</filename>
-</programlisting>
-</para>
- </sect3>
- <sect3 id="git-change-default-branch">
- <title>To change the default branch.</title>
- <para>
- If the Debian work is not on the <literal>master</literal> branch, change
- the default branch by editing the <filename>HEAD</filename> file in the
- bare repository on Salsa, and replace <literal>master</literal> by the
- name of the new default branch. For a branch called <literal>debian/unstable</literal>
- the contents of the file will <literal>refs/heads/debian/unstable</literal>.
- </para>
- </sect3>
- <sect3 id="push-package-to-salsa">
- <title>To push the package.</title>
- <para>(make sure you've added the salsa remote!), do the
- following: <code><command>git push</command> <option>origin
- master</option></code>. For the first push, it's necessary to specify
- <option>origin master</option>. The next time you will push, a
- <command>git push</command> will suffice.
- Or use the <literal>--set-upstream</literal> option, helps future use of git pull.<programlisting>
-<command>git</command> push --set-upstream
-</programlisting>
- </para>
- </sect3>
- <sect3 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>
- </sect3>
- <sect3 id="git-tag-release">
- <title>To tag a release</title>
- <para><code><command>git tag</command> <option>debian/x.y-z</option></code>.
- You can also easily retroactively make tags:
- <code><command>git tag</command> <option>debian/x.y-z</option> <option><commit hash></option></code>.
- Remember to <code><command>git push --tags</command></code>.
- </para>
- </sect3>
- <sect3 id="git-debian-version-from-commit">
- <title>If upstream manages his sources with Git.</title>
- <para>
- The following makefile script can help producing a version number when
- no Git tag is available:<programlisting>
-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)</programlisting>
- </para>
- </sect3>
- <sect3 id="git-pbuilder">
- <title>To make <command>gbp buildpackage</command> build the package with <command>pdebuild</command>.</title>
- <para>
- Add the following to the configuration file
- <filename>~/.gbp.conf</filename> or
- <filename>debian/gbp.conf</filename>:<programlisting>
-[DEFAULT]
-builder = ~/bin/git-pbuilder
-
-pristine-tar = True
-</programlisting>
- With this configuration file you're specifying that
- <command>gbp buildpackage</command> will use
- <filename>~/bin/git-pbuilder</filename> as the builder script.
- This is an example script you can use:<programlisting>
-#!/bin/sh
-set -e
-
-pdebuild --pbuilder cowbuilder --debbuildopts "-i\.git -I.git $*"
-rm ../*_source.changes</programlisting>
- This will build the package inside the default cowbuilder chroot,
- while passing any more parameters directly do
- <command>dpkg-buildpackage</command>.
- </para>
- </sect3>
- </sect2>
- <sect2 id="updating-git-package">
- <title>Updating a source package managed with Git</title>
- <para>Most source packages maintained as Git repositories in Debian Med are using the <command>gbp buildpackage</command> helper toolkit. In doubt, try this one first.</para>
- <para><command>gbp buildpackage</command>'s command <command>gbp import-orig</command> makes it easy to update of the <emphasis>upstream</emphasis> branch using upstream releases distributed as a compressed archive, and to merge these changes in the <emphasis>master</emphasis> 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>gbp buildpackage</command>, it is often unnecessary to rename the freshly downloaded original upstream archive.</para>
- <para>If you do not use <command>gbp buildpackage</command>, please use <command>pristine-tar</command> anyway to register the compressed archives that you upload to Debian as original upstream sources (the <literal>orig.tar.{gz|bz2|xz}</literal> file), with a command such as the following, where <literal>tarball</literal> is a path to the archive file and <literal>tag</literal> 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).<programlisting>
-<code><command>pristine-tar commit</command> <option>tarball</option> <option>tag</option></code>
-</programlisting></para>
- <para>Commit messages are sent to our commit mailing list with the <ulink
- url="https://github.com/mhagger/git-multimail/">git-multimail</ulink>
- tool. To avoid sending too many messages, consider setting the option
- <option>multimailhook.maxCommitEmails</option> to a low value, for instance
- 20; the default is 500…</para>
- </sect2>
- </sect1>
- <sect1 id="packaging">
- <title>Packaging</title>
- <sect2 id="packagingguidelines">
- <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
- <ulink url="https://www.debian.org/doc/manuals/maint-guide/">Debian New Maintainers' Guide</ulink>.
- </para>
- <para>See also the <ulink url="https://salsa.debian.org/med-team/community/package_template">package
- template</ulink> on Salsa.
- </para>
- <para>There is also the option of joining the <ulink url="https://wiki.debian.org/DebianMed/MoM">Mentoring
- if the Month</ulink> as student to get a personal training how to start working inside the Debian Med team.
- </para>
- </sect2>
- <sect2 id="itp">
- <title>Announcing intent to package</title>
- <para>If you intent to work on a Debian package you should follow
- the <ulink url="https://www.debian.org/devel/wnpp/#l1">normal Debian rules</ulink> and file a <acronym>WNPP</acronym> bug report.</para>
- <para>It is a good idea to keep the Debian Med mailing list
- <ulink url="mailto:debian-med at lists.debian.org">debian-med at lists.debian.org</ulink>
- <ulink url="https://www.debian.org/Bugs/Reporting#xcc"> in CC</ulink> 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.</para>
- <para>In addition, please add the package to the <quote>task</quote> file where it fits
- the best, and document your ITP number using the <command>WNPP</command> field name.</para>
- </sect2>
- <sect2 id="backports">
- <title>Backports</title>
- <para>
- Debian offers <ulink url="https://backports.debian.org">backports</ulink> 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 <link linkend="git-repository-structures">Git</link> repositories.
- The branch should be named using the release code names. As an example, the backports branch for Debian 9 ("stretch")
- should be named <literal>debian/stretch-backports</literal>, in accordance with
- <ulink url="http://dep.debian.net/deps/dep14/">DEP-14</ulink>.
- If you are developing on Stable, make sure to get the <literal>devscripts</literal> package from stretch-backports for <literal>dch --bpo</literal> to set the version properly.
- </para>
- <para>
- In Git, preparing a backport can be as simple as:
- <programlisting>
- <command>git checkout debian/VESIONTAG</command>
- <command>git checkout -b debian/stretch-backports</command>
- <command>dch --bpo</command>
- </programlisting>
- And then building the package using a Stable chroot after making any necessary adjustments to the packaging. See the
- <ulink url="https://wiki.debian.org/BuildingFormalBackports">wiki on backports</ulink> and
- the <ulink url="https://backports.debian.org">main backports website</ulink> for more detailed instructions.
- </para>
- <para>
- 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 <literal>dpkg-mergechangelogs</literal> (from the <literal>dpkg-dev</literal>
- package) to avoid getting unnecessary merge conflicts. See its manpage section "Integration with Git" for
- how to set that up.
- <programlisting>
- <command>git checkout debian/stretch-backports</command>
- <command>git merge debian/TO_BE_BACKPORTED_VERSION</command>
- <command>dch --bpo</command>
- </programlisting>
- Now, you can try building against a Stable chroot.
- </para>
- </sect2>
- <sect2 id="ppa">
- <title>PPA for Ubuntu</title>
- <para>
- Debian Med operates a <ulink url="https://launchpad.net/~debian-med/+archive/ppa">Personal Package Archive</ulink> (PPA) on Launchpad, where packages are backported for Ubuntu. There is currently no team policy on what to build.
- </para>
- <para>
- Because the space in the PPA is currently limited (4.0 GiB), we keep in the PPA only packages for <ulink url="https://wiki.ubuntu.com/Releases">still maintained</ulink> LTS Ubuntu version. Packages targeting an older Ubuntu will be removed.
- </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 <ulink url="https://www.debian.org/doc/debian-policy/#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: <code>2.12.0-1~natty1</code> (backport in PPA) < <code>2.12.0-1</code> (from Debian in Ubuntu) < <code>2.12.0-1natty1</code> (in PPA, containing additions) < <code>2.12.0-2</code> (from Debian in Ubuntu).
- Please follow the Ubuntu's <ulink url="https://help.launchpad.net/Packaging/PPA/BuildingASourcePackage#versioning">recommendations</ulink> for versioning packages in PPA.
- </para>
- <para>
- Packages sent to this PPA may be kept as branches in our repositories.
- </para>
- <para id="lintian-profile-ubuntu">
- Lintian checks are adapted to Ubuntu by setting the environment as follows: <code>LINTIAN_PROFILE=ubuntu</code>.
- </para>
- </sect2>
- <sect2 id="sidonubuntu">
- <title>Debian unstable chroot on Ubuntu</title>
- <para>
- cowbuilder-dist sid create
- cowbuilder-dist sid login
- </para>
- </sect2>
- <sect2 id="derivatives">
- <title>Derivatives working together with Debian Med</title>
- <para>
- Debian Med is proud that derivatives (like for instance <ulink url="http://environmentalomics.org/bio-linux/">Bio-Linux</ulink>) are profiting from our work inside Debian and we try to establish strong connections to these derivatives. With Bio-Linux the connection is as strong that a common workflow was created where Bio-Linux 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 <code><upstreamversion>-0<derivativename><derivativerevision></code> (which is the versioning scheme usually used by Ubuntu).
- </para>
- </sect2>
- <sect2 id="r-packages">
- <title>R packages</title>
- <para>
- Debian R packages should be maintained within the <ulink url="https://wiki.debian.org/Teams/r-pkg-team">Debian R Packages Team</ulink>.
- </para>
- <para>
- <ulink url="https://packages.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 acheived by adding the substitution variable <code>${R:Depends}</code> in the <emphasis>Depends</emphasis> field of the binary package.
- </para>
- </sect2>
- </sect1>
- <sect1 id="tasks">
- <title>Tasks</title>
- <para>The Debian Med <ulink url="https://blends.debian.org/blends">Debian Pure Blend</ulink> is organised by <ulink url="https://blends.debian.org/med/tasks">tasks</ulink>, that group packages around broad themes such as <ulink url="https://blends.debian.org/med/tasks/imaging">medical imaging</ulink> for instance. The tasks list programs that are already packaged in Debian as well as packages in preparation.</para>
- <para>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 Salsa have write access to the Blends Git repository. You can easily check out its sources with the command <command>debcheckout -a debian-med</command>.</para>
- <para>The syntax of the tasks files is very similar to Debian control files, and described in the <ulink url="https://blends.debian.org/blends/ch08.html#edittasksfiles">Debian Blends website</ulink>.</para>
- </sect1>
- <sect1 id="policy">
- <title>Policy</title>
- <sect2 id="debian-control">
- <title><filename>debian/control</filename></title>
- <orderedlist>
- <listitem>
- <formalpara>
- <title>Section</title>
- <para>Should be <quote>science</quote> for the source package.</para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>Priority</title>
- <para>Should be <quote>optional</quote> unless forbidden by the Debian policy (<ulink url="https://www.debian.org/doc/debian-policy/#priorities">see §2.5</ulink>). Packages of priority <quote>extra</quote> are excluded from some QA tests.</para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>Maintainer</title>
- <para>Maintainer should be <code>Debian Med Packaging Team <email>debian-med-packaging at alioth-lists.debian.net</email></code>. Please subscribe to this list if you list yourself in the <code>Uploaders:</code> field of one of Debian Med's packages. You can refer to the <ulink url="https://qa.debian.org/developer.php?login=debian-med-packaging@alioth-lists.debian.net">QA page</ulink> corresponding to this email to gather information about the packages.</para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>Uploaders</title>
- <para>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 <ulink url="https://www.debian.org/doc/manuals/developers-reference/pkgs.html#nmu-team-upload">team upload</ulink>.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <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.</para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>Homepage</title>
- <para>should be documented whenever possible</para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara id="vcs-url">
- <title>Vcs-Git: and Vcs-Browser:</title>
- <para>Please use the following templates, and refer to the Debian Policy
- <ulink url="https://www.debian.org/doc/debian-policy/#version-control-system-vcs-fields">§ 5.6.26</ulink>
- for details:<programlisting>
-Vcs-Browser: https://salsa.debian.org/med-team/<package>
-Vcs-Git: https://salsa.debian.org/med-team/<package>.git</programlisting>
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara id="testsuite">
- <title>Testsuite: autopkgtest</title>
- <para>
- Field and value to declare that a testsuite compatible with
- <ulink url="http://dep.debian.net/deps/dep8/">autopkgtest</ulink>
- is available. Such testsuite can be executed via the <command>adt-run</command>
- command from the <package>autopkgtest</package> package or the
- <command>sadt</command> command from the <package>devscripts</package>
- package. Note that since <command>dpkg</command> version 1.17.6,
- the <emphasis>XS-</emphasis> prefix is not necessary anymore for
- this field.
- </para>
- </formalpara>
- </listitem>
- </orderedlist>
- <para>
- It is a very good idea to use <command>Config::Model</command> to unify the formatting of <filename>debian/control</filename>.
- To do so make sure you have installed
- <formalpara>
- <command>apt-get</command> <option> install cme libconfig-model-dpkg-perl</option>
- </formalpara>
- and than you can simply call
- <formalpara>
- <command>cme</command> <option> fix dpkg-control</option>
- </formalpara>
- to get a properly formated, sanity checked <filename>debian/control</filename> file. Please note that sometimes you need to
- call this more than once. In case you want to use the cme GUI you also need to
- <formalpara>
- <command>apt-get</command> <option> install libconfig-model-tkui-perl</option>
- </formalpara>
- which enables you to do something like
- <formalpara>
- <command>cme</command> <option> edit dpkg</option>
- </formalpara>
- </para>
- </sect2>
-
- <sect2 id="debian-copyright">
- <title><filename>debian/copyright</filename></title>
- <para>
- We use the <ulink url="https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/">machine-readable format</ulink> for the <filename>debian/copyright</filename> file. The <computeroutput>Source</computeroutput> field does not need to contain the full URL to the particular version that is being packaged, since this can be determined by the <command>uscan</command> program with the <filename>debian/watch</filename> file (but note that some packagers use it as a bookmark to record when was the last copyright check). Please list yourself in the <computeroutput>Files: debian/*</computeroutput> 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 <quote>same as if it were in the public domain</quote> or <quote>same as the packaged program itself</quote>.
- </para>
- You can create a <filename>debian/copyright</filename> file from scratch using
- <formalpara>
- <command>cme</command> <option> update dpkg-copyright</option>
- </formalpara>
- <para>
- Alternatively you can create some reasonable skeleton for a <filename>debian/copyright</filename> file you can try the following:<programlisting>
-<command>sudo apt-get install</command> <replaceable>devscripts</replaceable> <replaceable>cdbs</replaceable>
-<command>licensecheck</command> <option>--copyright</option> <option>-r <replaceable>`find -type f`</replaceable></option> | <command>/usr/lib/cdbs/licensecheck2dep5</command> > <filename>debian/copyright</filename></programlisting>
- </para>
- <para>
- To verify the correct syntax of the <filename>debian/copyright</filename> file you can use:<programlisting>
-<command>cme </command> <option>check|fix|edit dpkg-copyright</option></programlisting>
- from package <filename>libconfig-model-dpkg-perl</filename> (see above).
- </para>
- </sect2>
-
- <sect2 id="debian-changelog">
- <title><filename>debian/changelog</filename></title>
- <para>Packages hosted in our Git repository, that have been modified but not uploaded must use <literal>UNRELEASED</literal> as a distribution name. This can be done automatically by declaring <literal><varname>DEBCHANGE_RELEASE_HEURISTIC</varname>=<replaceable>changelog</replaceable></literal> in <filename>~/.devscripts</filename> and using <command>dch</command>.</para>
- </sect2>
-
- <sect2 id="debian-upstream">
- <title><filename>debian/upstream</filename></title>
- <para>
- We use the <ulink url="https://wiki.debian.org/UpstreamMetadata#Fields">bibliographic information</ulink>
- which should be stored in the file <filename>debian/upstream</filename>. 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.
- </para>
- <para>
- A new development are registries of research software (e.g. SciCrunch's RRID,
- bio.tools, OMICtools). The metadata allows for references to publications
- and entries in these registries alike.
- </para>
- </sect2>
-
- <sect2 id="debian-gbp.conf">
- <title><filename>debian/gbp.conf</filename></title>
- <para>
- Include this file to document the layout of the repository. Packages managed
- with <command>gbp buildpackage</command> may omit default values.<programlisting>
-[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</programlisting>
- </para>
- </sect2>
-
- <sect2 id="debian-readme-source">
- <title><filename>debian/README.source</filename></title>
- <para>This file is recommended by the Policy (<ulink url="https://www.debian.org/doc/debian-policy/#source-package-handling-debian-readme-source">§ 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,…</para>
- </sect2>
-
- <sect2 id="debian-readme-test">
- <title><filename>debian/README.test</filename></title>
- <para>This file was (<ulink url="https://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 functionality can properly be tested.</para>
- </sect2>
-
- <sect2 id="debian-source-format">
- <title><filename>debian/source/format</filename></title>
- <para>
- This file sould 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.
- </para>
- </sect2>
-
- <sect2 id="debian-source-option">
- <title><filename>debian/source/options</filename></title>
- <para>
- For packages not using <link linkend="quilt">quilt</link> patches, for
- example when committing changes directly to the Debian branch, this file
- should contain <quote><literal>single-debian-patch</literal></quote> in
- order to emulate the <literal>1.0</literal> format. This is better than
- using the <literal>1.0</literal> format directly because the <literal>3.0
- (quilt)</literal> format brings other advantages, in particular the
- conservation of file permissions in the <filename type="directory">debian</filename>
- directory.
- </para>
- </sect2>
-
- <sect2 id="debhelper">
- <title>Debhelper</title>
- <para>Debhelper uses compatibility levels to control the behaviour of its commands. We currently recommend to use the level <emphasis>10</emphasis> which
- is available in current <emphasis>Stable</emphasis> and backported to <emphasis>Oldstable</emphasis>. However, there is no urgent need to
- touch packages only because it has an older Debhelper version.</para>
- <para>
- It is strongly recommended to use the short <emphasis>dh</emphasis> notation in <filename>debian/rules</filename> 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.
- </para>
- </sect2>
-
- <sect2 id="vcs">
- <title>Version control systems</title>
- <sect3 id="vcs-git">
- <title>Source package stored in a Git repository on Salsa</title>
- <para>
- Git repositories should be stored on <ulink url="https://salsa.debian.org/med-team/">Salsa</ulink>.
- </para>
- </sect3>
- <sect3 id="vcs-tags">
- <title>Tags</title>
- <para>
- Tags indicate the revision corresponding to uploaded packages.
- For a released package
- <literal>debian/</literal> is added before the package version number.
- </para>
- </sect3>
- </sect2>
- <sect2 id="new-package">
- <title>New package</title>
- <para>
- Try to inject a new package only after successfully building it with
- <command>dpkg-buildpackage</command> (or any wrapper around it). Use a
- file like <filename>debian/DRAFT</filename> to mention when the package
- is a draft.
- </para>
- </sect2>
- <sect2 id="new-packages-in-tasks">
- <title>The Debian Med Blend tasks</title>
- <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 Git
- source of the <package>debian-med</package> 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.
- </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 <link linkend="git-tag-release">Git</link> repository.
- </para>
- </sect2>
- <sect2 id="patches">
- <title>Handling patches</title>
- <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
- organise 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. You can use it with the <command>quilt</command> command.
- </para>
- <sect3 id="quilt">
- <title>Using <command>quilt</command></title>
- <para>Using quilt is rather easy.</para>
- <para>First, make sure you have correctly setup quilt: open
- <filename>.quiltrc</filename> in your home directory (create
- it if you don't have one), and make sure it looks like this:</para>
- <blockquote>
- <programlisting>QUILT_DIFF_ARGS="--no-timestamps --no-index"
-QUILT_REFRESH_ARGS="--no-timestamps --no-index"
-QUILT_PATCHES="debian/patches"</programlisting>
- </blockquote>
- <para>
- After this, you're ready to start working with quilt. See also the
- instructions in the <ulink url="https://www.debian.org/doc/manuals/maint-guide/modify.en.html#quiltrc">New
- Maintainer's Guide</ulink>.
- </para>
- <sect4 id="quilt-create">
- <title>Creating a patch</title>
- <para>To create a patch, use the <command>new</command> command.
- Run:</para>
- <blockquote>
- <para><userinput>
- <command>quilt new</command> <filename><patch_name>.patch</filename>
- </userinput></para>
- </blockquote>
- <para>This will create (if it doesn't exist yet) a
- <filename>debian/patches/series</filename> file, which
- contains all the patches to be applied by quilt. Moreover,
- the new patch is also the topmost (the currently
- applied).</para>
- <para>Now start editing files, with:</para>
- <blockquote>
- <para><userinput>
- <command>quilt edit</command> <filename><file></filename>
- </userinput></para>
- </blockquote>
- <para>and repeat the process for each file the patch is
- involved with. At the end, run</para>
- <blockquote>
- <para><userinput>
- <command>quilt refresh</command>
- </userinput></para>
- </blockquote>
- <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>).</para>
- <para>Make sure to write the patch header and use the
- <ulink url="http://dep.debian.net/deps/dep3/">DEP3 format</ulink>:</para>
- <blockquote>
- <para><userinput>
- <command>quilt header -e --dep3</command>
- </userinput></para>
- </blockquote>
- </sect4>
- <sect4 id="quilt-apply">
- <title>Applying and unapplying patches</title>
- <para>Just two easy commands to do the job:</para>
- <itemizedlist>
- <listitem><para><command>quilt pop</command> will unapply the topmost patch.</para></listitem>
- <listitem><para><command>quilt push</command> will apply the next patch in debian/patches/series.</para></listitem>
- </itemizedlist>
- <para>You can just add a "-a" flag to the commands above, to
- respectively apply/unapply all patches in the series.</para>
- <tip>
- <para>You can check which patches are applied/unapplied
- with, respectively, <command>quilt applied</command> and
- <command>quilt unapplied</command>.</para>
- </tip>
- </sect4>
- <sect4 id="quilt-edit">
- <title>Editing patches</title>
- <para>To edit a patch, first make it the topmost:</para>
- <blockquote>
- <para><userinput>
- <command>quilt push</command> <filename><patch_name></filename>
- </userinput></para>
- </blockquote>
- <para>If the patch is already applied, but is not the topmost,
- run <command>quilt pop</command> until it becomes the currently
- applied one.</para>
- <para>You can now run <command>quilt edit</command> on the files
- you want to change, and, when you're done, <command>quilt
- refresh</command>.</para>
- </sect4>
- <sect4 id="quilt-rename">
- <title>Renaming patches</title>
- <para>Sometimes it's useful to rename a patch. Without
- any hassle, do:</para>
- <blockquote>
- <para><userinput>
- <command>quilt rename -P</command> <filename><old_name>.patch</filename>
- <filename><new_name>.patch</filename>
- </userinput></para>
- </blockquote>
- </sect4>
- <sect4 id="quilt-other">
- <title>Other commands</title>
- <para>Please see <command>man 1 quilt</command> to have a
- comprehensive list of commands.</para>
- </sect4>
- </sect3>
- </sect2>
- </sect1>
- <sect1 id="faq">
- <title>FAQ</title>
- <sect2 id="autobuilder">
- <title>What to do if a large package does not build on a specific autobuilder architecture?</title>
- <para>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
- <blockquote>
- <command><arch>@buildd.debian.org</command>
- </blockquote>
- to blacklist the weaker candidates.
- </para>
- </sect2>
- </sect1>
-</article>
=====================================
policy_short.rst deleted
=====================================
@@ -1,68 +0,0 @@
-|image0|
-
-Policy
-======
-
-``debian/control``
-------------------
-
-1. **Section.**
-
- Should be “science” for the source package.
-
- .. list exceptions
-
-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|Git: 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: https://salsa.debian.org/med-team/<package>
- Vcs-Git: https://salsa.debian.org/med-team/<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.
-
-.. |image0| image:: /img/debian-med.jpg
View it on GitLab: https://salsa.debian.org/med-team/policy/commit/1cb4640d730eedbab281d570700a8699b6ff7f1d
--
View it on GitLab: https://salsa.debian.org/med-team/policy/commit/1cb4640d730eedbab281d570700a8699b6ff7f1d
You're receiving this email because of your account on salsa.debian.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/debian-med-commit/attachments/20190310/eca0faae/attachment-0001.html>
More information about the debian-med-commit
mailing list