Third Party Library Integration Policy

From PKP Wiki
Jump to: navigation, search

Choosing Libraries

Re-using code that others have written is one of the most basic strategies to keep development effort down and is nearly always preferable to writing code from scratch. There are many different ways in which other developers' work can be useful. Sometimes you can re-use their design, sometimes a few lines of code and sometimes even a whole existing library which is what this document is about.

Choosing third party solutions is not easy, though. Feature completeness is a necessary factor but far from sufficient. Secondary factors to be considered are:

  • license compatibility
  • system requirements (software and hardware)
  • extendability and openness (e.g. plugins, themes, etc.)
  • documentation quality
  • standards compliance, integration with other software
  • active and responsive development team (e.g. via bug-tracking)
  • professional project organization (e.g. release-management)
  • active and helpful user community (e.g. via forum)
  • additional support options (e.g. project management, chat-rooms, mailinglists, ...)
  • support for i18n/l10n
  • security architecture and security awareness of the project
  • adoption (number of existing users)
  • maintainability (upgrade process, backwards compatibility, etc.)
  • availability (Linux packages, Mac version, Windows installation file, ...)
  • compatibility with the existing development, build and packaging process (e.g. tool support, Debian package, ...)

This list is not complete and differs depending on the kind of software you want to integrate. These are generic criteria, though, that nearly always will be relevant.

Library Integration

The most important thing to think of when integrating libraries is maintainability, for ourselves and above all for our users:

  • Make sure that you think about how users can integrate existing installations of the library. Imagine that they have a stock version of the library installed on their system. They should be able to use it rather than having to maintain the copy we distribute. If not respected, our software can be considerably less secure, maintainable or usable from a user's point of view.
  • Make sure that you support a wide range of library versions so that your software works even with an older version of the library. Try not to use the newest features if they are not broadly available. Document and communicate which versions are acceptable.
  • Make sure that the team is informed about new versions of the library, especially security updates.
  • Make sure that you only use the documented public stable API of the library so that library upgrades do not break your code.

Extending Libraries

  • Never apply changes to files that are distributed with a library.
  • Make sure that your extensions can easily be maintained apart from the library itself. This means that your extensions should usually live in their own directory structure. Make sure that your extension can be located separately from the library so that the user is free to have the library installed in a non-standard location.
  • Make sure that you only use the documented extension points or plug-in architecture of the library so that library upgrades do not break your extension.

Fixing Bugs in a Library

  • If you find a bug in a library then do not fix it in place (see library integration and extension above).
  • Create a patch that fixes the problem and send it upstreams to the library developers. If you have chosen an actively maintained library (see selection criteria), the fix should quickly become part of the main code line.
  • In the meantime try to find a userland workaround that does not change the library code. If this is not possible then maintain the patch you sent upstream apart from the library code. Do not check in the patched library code but the patch.
  • Patch software like quilt can help you to maintain a larger number of patches. It also helps you to get rid of specific patches easily once they've been integrated upstream.
  • If the upstream project does not react for a while then it might be useful to submit you patch to downstream projects, especially Linux distributions. They might fix the problem for a large part of our user community before the upstream project becomes active.