sandbox/GettingStuffPackaged.rst

   1 :date: 2011-08-20 20:00:00
   2 :tags: neuroscience, software, packaging
   3
   4 .. _chap_neurosoftware_packaging:
   5
   6 What does it take to get some software packaged?
   7 ================================================
   8
   9 We often get contacted by people who wrote some scientific software and
  10 would like to see it being available from the NeuroDebian repository.
  11 Most of these developers don't know what it actually means to *package*
  12 software, how time-consuming the process is, and who needs to do what to
  13 get things done.
  14
  15 There is already a lot of information about *distribution packaging* on the
  16 web, including "best-practices" documentation for upstream_-developers,
  17 such as `Debian's upstream guide`_, and it would be pointless to repeat all
  18 these bits here. Instead we will focus on a few core aspects that we found
  19 to be the most ignored and misunderstood concepts that heavily influence
  20 the speed and complexity of the *packaging process*.
  21
  22 .. _upstream: http://en.wikipedia.org/wiki/Upstream_(software_development)
  23 .. _Debian's upstream guide: http://wiki.debian.org/UpstreamGuide
  24
  25 So what exactly is a *package*? The ultra-short summary: it is first and
  26 foremost an executable description of how to build software from source and
  27 install the resulting binaries, while ensuring compatibility and
  28 interoperability with other parts of a particular system.  Hence, although
  29 Debian-based operating systems install packages containing *binaries*, the
  30 main focus of the packaging process is on the **source package**.  The
  31 end-product of the packaging process is a source package that enables
  32 **anybody** to produce binary packages in a *uniform* and *deterministic*
  33 fashion, with an exhaustive description of its dependencies.
  34
  35 To understand how that is done any interested person **needs** to read a
  36 fair bit of documentation, for example a `packaging tutorial`_, and the
  37 `Debian policy`_ -- the ultimate guidelines for proper Debian packages.
  38 But albeit being an interesting read for anyone, it is actually the
  39 *package maintainer*'s job to get all this done right. However, there are a
  40 few key aspects about packaging that any developer should know, as they
  41 will make the difference between getting a package done in a few hours, or
  42 only after weeks, months, or years of tedious work. These are:
  43
  44 * A reliable versioning scheme
  45 * Exhaustive documentation of involved licenses
  46 * Clear separation of 3rd-party code
  47 * An open ear
  48
  49
  50 Have a deterministic version!
  51 -----------------------------
  52
  53 Software need a version, packages need a version. The version is used to
  54 determine whether an update is available, whether a particular package can
  55 be used to satisfy a versioned dependency of another package, to associate
  56 bug reports with source code, and, of course, to tell users what version
  57 of a software they are running.  Surprisingly, there is a lot of scientific
  58 software out there that doesn't have a version, or pretends to have one,
  59 but the actual source code changes without a corresponding change in the
  60 version. This is **wrong**. If you want to have your software packaged, have
  61 a reliable version scheme:
  62
  63 * *Increment* the version whenever you change the code (even for tiny
  64   changes).
  65 * Put the version into the filename of your source code download.
  66 * And/or use a `version control system`_ (VCS) that does that versioning for
  67   you.
  68
  69 .. _version control system: http://en.wikipedia.org/wiki/Comparison_of_revision_control_software
  70
  71 If you don't have a version the package maintainer needs to invent one.
  72 This could be based on the time-stamp of a download, or the last
  73 modification time of any file in the source code. But whatever the
  74 maintainer will come up with, it will take time, and it will be different
  75 from what you do. This will make packaging more complex, and it will
  76 confuse users.
  77
  78
  79 Be conscious about all licenses!
  80 --------------------------------
  81
  82 Licenses are important. They determine whether a 3rd-party, such as a
  83 Debian, is legally allowed to redistribute your software. They determine
  84 whether a package maintainer is allowed to modify software for improved
  85 system integration or bug fixing. They also have an impact on people's
  86 motivation to contribute to a project. For example, many people out there
  87 would rather not invest their time in software with restrictive licenses.
  88
  89 Be aware that the collection of *all* licenses in your source code form the
  90 legal terms of your software. We often see "open-source" software that is "free
  91 to use", but depends on, or includes source code that "may not be
  92 redistributed".  This is probably **wrong**. Moreover, we encountered quite a
  93 few projects that hadn't picked any license at all. If you intend other people
  94 to use your tools this is **wrong** too, as no license typically means no
  95 permissions at all -- not even download and use.
  96
  97 The package maintainer needs to sort all these things out, needs to
  98 make sure that redistribution doesn't impose a legal threat to anyone
  99 (including repository mirror operators), and needs to make sure that people
 100 expecting free and open-source software only get free and open-source
 101 software.
 102
 103 If you want to facilitate the packaging process: Make sure that you are
 104 aware of all licenses covering the source code of your software. Make sure
 105 to document them properly in the source code.  Make sure that the licenses
 106 covering the source code are compatible to each other (e.g. you cannot
 107 release under the GPL_ if the license of some other part of your code says
 108 "must not be used on Thursdays"). The easiest way to avoid unnecessary
 109 complications is to use a `standard license`_ (such as BSD, or GPL) that
 110 are known and have been evaluated by legal experts regarding their
 111 implications and their compatibility with each other. Check if your legal
 112 terms comply with the `open-source definition`_ or the `Debian free software
 113 guidelines`_ (that are the basis of this definition).
 114
 115 .. _GPL: http://www.gnu.org/copyleft/gpl.html
 116 .. _open-source definition: http://www.opensource.org/docs/osd
 117 .. _Debian free software guidelines: http://www.debian.org/social_contract#guidelines
 118
 119
 120 Allow for modularity!
 121 ---------------------
 122
 123 Usually, software authors already have means to build their code for Debian
 124 or Ubuntu systems before contacting a potential packager. However, quite
 125 often these procedures need to be adjusted (and sometimes even abandoned)
 126 for a distribution package. A prominent reason is the inclusion of
 127 3rd-party source code. Virtually all software is built on top of some other
 128 software -- may it be a GUI toolkit or a numerical library. Occasionally,
 129 it makes sense to include the more exotic dependencies into a source
 130 distribution of some software, mainly to make building and installing
 131 easier for people on less fortunate platforms.
 132
 133 However, for a distribution package such setup is typically not acceptable.
 134 An operating system like Debian is a modular system were duplication needs
 135 to be avoided. There should only be a single copy of a particular library
 136 or tool in the distribution. All packages that require a piece of 3rd-party
 137 software need to declare a dependency on the corresponding package and
 138 should not ship their own copy. This has the advantage that bugs in a
 139 software can be fixed in a single place and all dependent software
 140 automatically benefits from this fix, without further human intervention.
 141 Only a modular design like this makes it possible to successfully maintain
 142 an integrated system of tens of thousands software packages with a
 143 reasonable amount of manpower.
 144
 145 So if your source distribution contains 3rd-party software, clearly
 146 identify its origin and version (the license as well, of course). This
 147 informs the packager which dependencies need to be declared, or potentially
 148 which other software still needs to be packaged separately, in order to
 149 serve as a dependency.
 150
 151 As a consequence of the dependency system, you should not modify 3rd-party
 152 software. If you, for example, take the source of a library and modify it a
 153 bit to make it easier for you to do a certain task, there is suddenly the
 154 need for having two almost identical libraries in the operating system. The
 155 package for your software cannot use the system package for this library,
 156 because it is modified. Instead of keep a modified version: if you need to
 157 fix bugs in 3rd-party software, make sure to forward the fixes to the
 158 original developers. If you need to adapt its behavior, try to do it in a
 159 way that is modular, keeping the adaptor separate from the 3rd-party code.
 160 This will make it much easier for you to track future developments of this
 161 code, as well as help the packager integrate your software into the
 162 operating system.
 163
 164 Also, you will significantly facilitate the packaging process if your
 165 build-system allows to optionally build and link against system libraries
 166 instead of the convenience copies that may be included in your source code.
 167 Keep in mind that anything that is *required* for packaging software for
 168 Debian needs to be added or modified by the package maintainer. All
 169 modifications can potentially change the behavior of your software and may
 170 confuse users and/or result in unnecessary support requests that need to be
 171 dealt with. Be assured that it is in the very interest of the package
 172 maintainer to keep the differences minimal. If you keep modularity aspects
 173 in mind while developing you can massively facilitate a packaging effort.
 174
 175
 176 Be prepared for feedback!
 177 -------------------------
 178
 179 The package maintainer might send you a few patches during the initial
 180 packaging that either fix bugs on the Debian platform or that were added to
 181 gain compliance with the Debian policy. Be prepared to evaluate these
 182 patches and merge them into your code base or discuss necessary
 183 modifications. The package maintainer needs to keep track of all
 184 modifications done to your software and needs to refresh them for every new
 185 release that is made. If you make it easy for the maintainer to do this
 186 work, for example quickly merging modifications, by exposing a version
 187 control system to track modifications, or at least a reliable communication
 188 channel that informs the maintainer about the fate of the patches, you will
 189 help to streamline long-term package maintenance and contribute to a
 190 reliable package. All this will help disseminating your software in an
 191 extremely convenient form to a very large audience.