sandbox/GettingStuffPackaged.rst

   1 :date: 2011-08-20 20:00:00
   2 :tags: neuroscience, software, packaging
   3
   4 .. _chap_faciliate_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 upstream developer should know, as
  41 they will make the difference between getting a package done in a few
  42 hours, or 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 needs versions, packages need versions. A 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 make a release of your project, and
  64   make a *new* release whenever you want to push out some changes to an
  65   existing release (even for tiny changes).
  66 * Put the version into the filename of your source or binary download.
  67 * And/or use a `version control system`_ (VCS) that helps you track changes
  68   and associates them with unique identifiers that could serve as a
  69   version (if nothing better is available).
  70
  71 .. _version control system: http://en.wikipedia.org/wiki/Comparison_of_revision_control_software
  72
  73 If you don't have a deterministic version, the package maintainer needs to
  74 come up with one.  Such custom version could be based on the time-stamp of
  75 a download, or the last modification time of any file in the source
  76 distribution.  But whatever the maintainer will come up with, it will take
  77 time to implement, and it will be different from what you do. This will
  78 make packaging more complex, and it will confuse users.
  79
  80
  81 Be conscious about all licenses!
  82 --------------------------------
  83
  84 Licenses are important. They determine whether a 3rd-party, such as a
  85 Debian, is legally allowed to redistribute your software. They determine
  86 whether a package maintainer is allowed to modify software for improved
  87 system integration or bug fixing. They also have an impact on people's
  88 motivation to contribute to a project -- many people out there would rather
  89 not invest their precious time in software with restrictive licenses.
  90
  91 Be aware that the collection of *all* licenses in your source code form the
  92 legal terms of your software. We often see "open-source" software that is "free"
  93 (to use), but depends on, or includes source code that "may not be
  94 redistributed".  This is most likely **wrong**. Moreover, we encountered quite a
  95 few projects that hadn't picked any license at all. If you intend other people
  96 to use your tools this is **wrong** too, as no license typically means no
  97 permissions at all -- not even to download or to use.
  98
  99 The package maintainer needs to sort all these things out, needs to
 100 make sure that redistribution doesn't impose a legal threat to anyone
 101 (including repository mirror operators), and needs to make sure that people
 102 expecting free and open-source software only get free and open-source
 103 software.
 104
 105 If you want to facilitate the packaging process: Make sure that you are
 106 aware of all licenses covering the source code and other materials (such as
 107 documentation and images) in your software. Make sure to document them
 108 properly.  Make sure that the licenses covering the source code are
 109 compatible to each other (e.g. you cannot release under the GPL_ if the
 110 license of some other part of your code says "must not be used on
 111 Thursdays"). The easiest way to avoid unnecessary complications is to use a
 112 `standard license`_ (such as BSD, or GPL) that are known and have been
 113 evaluated by legal experts regarding their implications and their
 114 compatibility with each other. For any license, check if your legal terms
 115 comply with the `open-source definition`_ or the `Debian free software
 116 guidelines`_ (that are the basis of this definition).
 117
 118 .. keep to details for a dedicated "what license?" post
 119
 120 .. _GPL: http://www.gnu.org/copyleft/gpl.html
 121 .. _open-source definition: http://www.opensource.org/docs/osd
 122 .. _Debian free software guidelines: http://www.debian.org/social_contract#guidelines
 123
 124
 125 Allow for modularity!
 126 ---------------------
 127
 128 Usually, software authors already have means to build their code for Debian
 129 or Ubuntu systems before contacting a potential packager. However, quite
 130 often these procedures need to be adjusted (and sometimes even abandoned)
 131 for a distribution package. A prominent reason is the inclusion of
 132 3rd-party source code. Virtually all software is built on top of some other
 133 software -- may it be a GUI toolkit or a numerical library. Occasionally,
 134 it makes sense to include the more exotic dependencies into a source
 135 distribution of some software, mainly to make building and installing
 136 easier for people on less fortunate platforms.
 137
 138 However, for a distribution package such setup is typically not acceptable.
 139 An operating system like Debian is a modular system were duplication needs
 140 to be avoided. There should only be a single copy of a particular library
 141 or tool in the distribution. All packages that require a piece of 3rd-party
 142 software need to declare a dependency on the corresponding package and
 143 should not ship their own copy. This has the advantage that bugs in a
 144 software can be fixed in a single place and all dependent software
 145 automatically benefits from this fix, without further human intervention.
 146 Only a modular design like this makes it possible to successfully maintain
 147 an integrated system of tens of thousands software packages with a
 148 reasonable amount of manpower.
 149
 150 So if your source distribution contains 3rd-party software, clearly
 151 identify its origin and version (the license as well, of course). This
 152 informs the packager which dependencies need to be declared, or potentially
 153 which other software still needs to be packaged separately, in order to
 154 serve as a dependency.
 155
 156 As a consequence of the dependency system, you should avoid modifying
 157 3rd-party software. If you, for example, take the source of a library and
 158 modify it a bit to make it easier for you to do a certain task, there is
 159 suddenly the need for having two almost identical libraries in the
 160 operating system. The package for your software cannot use the system
 161 package for this library, because it is modified. Instead of keeping a
 162 modified version forever: if you need to fix bugs in 3rd-party software,
 163 make sure to forward the fixes to the original developers. If you need to
 164 adapt its behavior, try to do it in a way that is modular, keeping the
 165 adaptor separate from the 3rd-party code.  This will make it much easier
 166 for *you* to track future developments of this code, as well as help the
 167 packager integrate your software into the operating system.
 168
 169 Also, you will significantly facilitate the packaging process if your
 170 build-system allows to optionally build and link against system libraries
 171 instead of the convenience copies that may be included in your source code.
 172 Keep in mind that anything that is *required* for packaging software for
 173 Debian needs to be added or modified by the package maintainer. All
 174 modifications can potentially change the behavior of your software and may
 175 confuse users and/or result in unnecessary support requests that need to be
 176 dealt with. Be assured that it is in the very interest of the package
 177 maintainer to keep the differences minimal. If you keep modularity aspects
 178 in mind while developing, you can massively facilitate a packaging effort.
 179
 180
 181 Be prepared for feedback!
 182 -------------------------
 183
 184 The package maintainer might send you a few patches during the initial
 185 packaging that either fix bugs on the Debian platform or that were added to
 186 gain compliance with the Debian policy. Be prepared to evaluate these
 187 patches and merge them into your code base or discuss necessary
 188 modifications. The package maintainer needs to keep track of all
 189 modifications done to your software and needs to refresh them for every new
 190 release that is made. If you make it easy for the maintainer to do this
 191 work, for example quickly merging modifications, exposing a version
 192 control system to track modifications, or at least a reliable communication
 193 channel that informs the maintainer about the fate of the patches, you will
 194 help to streamline long-term package maintenance and contribute to a
 195 reliable package. All this will help disseminating your software in an
 196 extremely convenient form to a very large audience.
 197
 198
 199 On a final note: If you keep these things in mind you won't only make it
 200 easier for a packager. You will also have removed most hurdles for a smooth
 201 packaging in general. Now you could actually think about doing the
 202 packaging yourself.  Take a look at a `packaging tutorial`_ to get a sense
 203 of what it would involve. If you decide to venture down this road, you are
 204 very welcome to contact `us@NeuroDebian`_ -- we would be glad to guide you
 205 through an efficient packaging process and upload fully packaged software
 206 for psychological and neuroscience research into the main Debian archive
 207 and the NeuroDebian repository.
 208
 209 .. _us@NeuroDebian: http://neuro.debian.net/#contacts