This is an automated email from the git hooks/post-receive script. misterc-guest pushed a commit to branch master in repository policy.
commit 6df927ce46f1713c3439c4a4c806c83dfe5ecda9 Author: Michael R. Crusoe <[email protected]> Date: Sat Feb 6 05:42:56 2016 -0800 strip to base policy & add Makefile --- Makefile | 17 + policy.rst | 1141 +----------------------------------------------------------- 2 files changed, 23 insertions(+), 1135 deletions(-) diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..c22a4b8 --- /dev/null +++ b/Makefile @@ -0,0 +1,17 @@ +PUBLISHHOST=alioth +PUBLISHDIR=/home/groups/debian-med/htdocs/docs + +all: policy + +policy: + pandoc -f html -o policy.html policy.xml 2>/dev/null + +clean: + rm -f policy.html + +publish: policy + rsync -a policy.* $(PUBLISHHOST):$(PUBLISHDIR) + ssh $(PUBLISHHOST) "chmod g+w $(PUBLISHDIR)/policy.*" + +install-deps: + sudo apt-get install pandoc diff --git a/policy.rst b/policy.rst index bbf6c83..19e7725 100644 --- a/policy.rst +++ b/policy.rst @@ -1,776 +1,5 @@ |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 ====== @@ -781,6 +10,8 @@ Policy Should be “science” for the source package. + .. list exceptions + 2. **Priority.** Should be “optional” unless forbidden by the Debian policy (`see @@ -815,7 +46,7 @@ Policy should be documented whenever possible -7. **Vcs-Svn: and Vcs-Browser:.** +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>`__ @@ -823,15 +54,15 @@ Policy :: - Vcs-Browser: http://anonscm.debian.org/viewvc/debian-med/trunk/packages/<package>/trunk/ + Vcs-Browser: https://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 + Vcs-Browser: https://anonscm.debian.org/cgit/debian-med/<package>.git + Vcs-Git: https://anonscm.debian.org/git/debian-med/<package>.git 8. **Testsuite: autopkgtest.** @@ -842,364 +73,4 @@ Policy 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
