:date: 2011-08-20 20:00:00
:tags: neuroscience, software, packaging
-.. _chap_neurosoftware_packaging:
+.. _chap_faciliate_neurosoftware_packaging:
What does it take to get some software packaged?
================================================
`Debian policy`_ -- the ultimate guidelines for proper Debian packages.
But albeit being an interesting read for anyone, it is actually the
*package maintainer*'s job to get all this done right. However, there are a
-few key aspects about packaging that any developer should know, as they
-will make the difference between getting a package done in a few hours, or
-only after weeks, months, or years of tedious work. These are:
+few key aspects about packaging that any upstream developer should know, as
+they will make the difference between getting a package done in a few
+hours, or only after weeks, months, or years of tedious work. These are:
* A reliable versioning scheme
* Exhaustive documentation of involved licenses
* Clear separation of 3rd-party code
* An open ear
-.. instead of saying that "packaging is only for us, Debian gurus",
-.. here would be a good point to say that "having those requirements
-.. fullfilled packaging becomes and easy task, which could be tackled
-.. having read the tutorial and then seeking the
-.. mentorship/sponsorship".
Have a deterministic version!
-----------------------------
-Software need a version, packages need a version. The version is used to
+Software needs versions, packages need versions. A version is used to
determine whether an update is available, whether a particular package can
be used to satisfy a versioned dependency of another package, to associate
bug reports with source code, and, of course, to tell users what version
version. This is **wrong**. If you want to have your software packaged, have
a reliable version scheme:
-.. altogether a bit of a mix -- we don't increment any version while
-.. working on the code -- we increment whenever making it publicly
-.. available outside of VCS
-
-.. also, strictly speaking, "sources" contain not only the 'code' which
-.. we need to version -- docs/images/data/etc; thus I have replaced 'code'
-.. on some occurrences
-
-* *Increment* the version whenever you change publicly available
- release or tarball of your project (even for tiny changes).
+* *Increment* the version whenever you make a release of your project, and
+ make a *new* release whenever you want to push out some changes to an
+ existing release (even for tiny changes).
* Put the version into the filename of your source or binary download.
-* And/or use a `version control system`_ (VCS) that does that versioning for
- you.
-
-.. VCS doesn't do versioning per se -- it does changes tracking
-.. possibly with unique identified which could be treated as a version
+* And/or use a `version control system`_ (VCS) that helps you track changes
+ and associates them with unique identifiers that could serve as a
+ version (if nothing better is available).
.. _version control system: http://en.wikipedia.org/wiki/Comparison_of_revision_control_software
-If you don't have a deterministic version, the package maintainer
-needs to come up with one, possibly complementing to the original
-version which remains stale while released material changes.
-Such custom version could be based on the time-stamp of a download, or the last
-modification time of any file in the source distribution. But whatever the
-maintainer will come up with, it will take time, and it will be different
-from what you do. This will make packaging more complex, and it will
-confuse users.
+If you don't have a deterministic version, the package maintainer needs to
+come up with one. Such custom version could be based on the time-stamp of
+a download, or the last modification time of any file in the source
+distribution. But whatever the maintainer will come up with, it will take
+time to implement, and it will be different from what you do. This will
+make packaging more complex, and it will confuse users.
Be conscious about all licenses!
Debian, is legally allowed to redistribute your software. They determine
whether a package maintainer is allowed to modify software for improved
system integration or bug fixing. They also have an impact on people's
-motivation to contribute to a project. For example, many people out there
-would rather not invest their time in software with restrictive licenses.
+motivation to contribute to a project -- many people out there would rather
+not invest their precious time in software with restrictive licenses.
Be aware that the collection of *all* licenses in your source code form the
-legal terms of your software. We often see "open-source" software that is "free
-to use", but depends on, or includes source code that "may not be
-redistributed". This is probably **wrong**. Moreover, we encountered quite a
+legal terms of your software. We often see "open-source" software that is "free"
+(to use), but depends on, or includes source code that "may not be
+redistributed". This is most likely **wrong**. Moreover, we encountered quite a
few projects that hadn't picked any license at all. If you intend other people
to use your tools this is **wrong** too, as no license typically means no
permissions at all -- not even to download or to use.
software.
If you want to facilitate the packaging process: Make sure that you are
-aware of all licenses covering the source code and other materials
-(such as documentation and images) in your software. Make sure
-to document them properly. Make sure that the licenses
-covering the source code are compatible to each other (e.g. you cannot
-release under the GPL_ if the license of some other part of your code says
-"must not be used on Thursdays"). The easiest way to avoid unnecessary
-complications is to use a `standard license`_ (such as BSD, or GPL) that
-are known and have been evaluated by legal experts regarding their
-implications and their compatibility with each other. Beware that
-standard licenses created to cover programs source code are not always
-appropriate for content (e.g. images and documentation) or data (which
-might not even be copyrightable in some jurisdictions such as USA). You
-can find some of popular licenses for content and data on
-`Open Knowledge Definition (OKD)
-<http://www.opendefinition.org/licenses>`_ website. For any license, check if your legal
-terms comply with the `open-source definition`_ or the `Debian free software
+aware of all licenses covering the source code and other materials (such as
+documentation and images) in your software. Make sure to document them
+properly. Make sure that the licenses covering the source code are
+compatible to each other (e.g. you cannot release under the GPL_ if the
+license of some other part of your code says "must not be used on
+Thursdays"). The easiest way to avoid unnecessary complications is to use a
+`standard license`_ (such as BSD, or GPL) that are known and have been
+evaluated by legal experts regarding their implications and their
+compatibility with each other. For any license, check if your legal terms
+comply with the `open-source definition`_ or the `Debian free software
guidelines`_ (that are the basis of this definition).
+.. keep to details for a dedicated "what license?" post
+
.. _GPL: http://www.gnu.org/copyleft/gpl.html
.. _open-source definition: http://www.opensource.org/docs/osd
.. _Debian free software guidelines: http://www.debian.org/social_contract#guidelines
which other software still needs to be packaged separately, in order to
serve as a dependency.
-As a consequence of the dependency system, you should not modify 3rd-party
-software. If you, for example, take the source of a library and modify it a
-bit to make it easier for you to do a certain task, there is suddenly the
-need for having two almost identical libraries in the operating system. The
-package for your software cannot use the system package for this library,
-because it is modified. Instead of keep a modified version: if you need to
-fix bugs in 3rd-party software, make sure to forward the fixes to the
-original developers. If you need to adapt its behavior, try to do it in a
-way that is modular, keeping the adaptor separate from the 3rd-party code.
-This will make it much easier for you to track future developments of this
-code, as well as help the packager integrate your software into the
-operating system.
+As a consequence of the dependency system, you should avoid modifying
+3rd-party software. If you, for example, take the source of a library and
+modify it a bit to make it easier for you to do a certain task, there is
+suddenly the need for having two almost identical libraries in the
+operating system. The package for your software cannot use the system
+package for this library, because it is modified. Instead of keeping a
+modified version forever: if you need to fix bugs in 3rd-party software,
+make sure to forward the fixes to the original developers. If you need to
+adapt its behavior, try to do it in a way that is modular, keeping the
+adaptor separate from the 3rd-party code. This will make it much easier
+for *you* to track future developments of this code, as well as help the
+packager integrate your software into the operating system.
Also, you will significantly facilitate the packaging process if your
build-system allows to optionally build and link against system libraries
confuse users and/or result in unnecessary support requests that need to be
dealt with. Be assured that it is in the very interest of the package
maintainer to keep the differences minimal. If you keep modularity aspects
-in mind while developing you can massively facilitate a packaging effort.
+in mind while developing, you can massively facilitate a packaging effort.
Be prepared for feedback!
modifications. The package maintainer needs to keep track of all
modifications done to your software and needs to refresh them for every new
release that is made. If you make it easy for the maintainer to do this
-work, for example quickly merging modifications, by exposing a version
+work, for example quickly merging modifications, exposing a version
control system to track modifications, or at least a reliable communication
channel that informs the maintainer about the fate of the patches, you will
help to streamline long-term package maintenance and contribute to a
reliable package. All this will help disseminating your software in an
extremely convenient form to a very large audience.
+
+
+On a final note: If you keep these things in mind you won't only make it
+easier for a packager. You will also have removed most hurdles for a smooth
+packaging in general. Now you could actually think about doing the
+packaging yourself. Take a look at a `packaging tutorial`_ to get a sense
+of what it would involve. If you decide to venture down this road, you are
+very welcome to contact `us@NeuroDebian`_ -- we would be glad to guide you
+through an efficient packaging process and upload fully packaged software
+for psychological and neuroscience research into the main Debian archive
+and the NeuroDebian repository.
+
+.. _us@NeuroDebian: http://neuro.debian.net/#contacts
projects / neurodebian.git / commitdiff