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 <[email protected]> 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 [email protected] 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:[email protected]>`__ (``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://[email protected]/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 [email protected] `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 [email protected]``. + 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/[email protected]>`__ + 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/[email protected]>`__. 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 _______________________________________________ debian-med-commit mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/debian-med-commit
