[Debian GNUstep maintainers] RFS: GNUstep packages naming scheme

[Yavor Doganov]

I finally found some time to work on the internal policy document I
talked about last year.  Progress is extremely slow but I decided to
publish at least the first section.

The plan is:

1) Agree among ourselves about the naming scheme of GNUstep packages.
2) Ask for ftpmasters' opinion about it.
3) Eventually, make corrections according to ftpmasters' comments.

The general plan is to publish this document when it's ready and we
all agree with its contents.  We should decide how to distribute it:

* As part of the gnustep-make-doc package.  This is straightforward
  but somewhat "dirty" because it has little to do with upstream
  GNUstep Make and its manual.  Another disadvantage is that updates
  to the document will trigger unnecessary upgrades of the
  gnustep-common package for all users that have it installed.

* As a separate native package:
  - gnustep-policy (short and clear but may be confused with some
    upstream policy).
  - debian-gnustep-policy
  - pkg-gnustep-policy
  - gnustep-team-policy
  - something else.

* As a separate binary package of a native source package that also
  provides Debian-specific stuff (dh_gnustep, etc.) we currently ship
  in the gnustep-make package.

All of this is not urgent, I guess at least a few months will pass
until it's ready.

Comments welcome (both for the document itself and the plan).
-------------- next part --------------
Debian GNUstep Policy
*********************

This manual is a guide for maintainers of Debian GNUstep packages and
internal policy for the Debian GNUstep Team.
Last updated on 26.11.2019.

   Copyright (C) 2019 Debian GNUstep Team

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License."

1 About This Document
*********************

This manual is an attempt to achieve several goals simultaneously:

   * To serve as a supplement to the Debian Policy, describing
     particular details that are only relevant for GNUstep packages.
     However, it is _not_ a replacement for it, no document can ever be.
     GNUstep packages must still conform to the Debian Policy as all
     other packages in the Debian distribution.

   * To document specific best practices and conventions for GNUstep
     packages, with the ultimate goal of achieving uniformity and better
     quality of the packages.

   * To serve as introduction to Debian package maintainers who are not
     intimately familiar with GNUstep but wish to maintain a GNUstep
     package.

   * To serve as introduction to upstream GNUstep developers who wish to
     maintain their package in Debian, or for those who might be curious
     to know about the problems and challenges we are facing.

   * To be something like a guide for Debian Developers who sponsor
     uploads of GNUstep packages.  Sponsors usually have great
     understanding of Debian Policy and best packaging practices, but
     sometimes lack specific knowledge in some areas--this is natural
     and expected since the diversity is immense.

   * To document some bitter experience and grave mistakes from the past
     which should never be repeated.

   * To provide suggestions and tips for improving the quality of
     GNUstep packages in Debian.

   This document is organized in a way that it can be used as a quick
reference when packaging GNUstep software for Debian.  Therefore, it has
the appropriate Texinfo indexing commands which allow index-based search
in a capable 'info-browser'.  All references to external documents are
made so that they work if the appropriate documentation packages
('debian-policy', 'gnustep-make-doc', 'gcc-doc', etc.)  are installed on
a Debian system.  The links are tailored so they work for browsing the
manuals in Info format; they may not work properly with other
documentation formats.

   The manual follows roughly the normative meanings of the words
'must', 'should' and 'may', as well as the adjectives 'required',
'recommended' and 'optional', as described in the Debian Policy.  *Note
(debian-policy)Scope::.

2 Package Types and Names
*************************

There are several different types of GNUstep packages; some of them
traditionally have generic names, a heritage from NeXT/Apple and a
practice that many upstream developers still follow.  With the large set
of packages that Debian provides, it is almost certain that at some
point they would clash with some other non-GNUstep package.  In order
not to pollute the general namespace, the Debian ftp-masters have
enforced a certain naming convention, reserving a separate namespace for
GNUstep.  Unfortunately, it is not used consistently and it was never
documented.  This section is an attempt to fix this.

   The first GNUstep packages that were uploaded to Debian matched the
upstream names, that's why the oldest packages lack the '.app' suffix
('gnumail', 'gworkspace' or 'affiche', to name a few).  Some other
packages have unnecessary suffixes like '.tool' or '.framework', or even
awkward names like 'addresses-for-gnustep'.

   Here is a description of the package types and package names which
must be used consistently.

Tools
     These are non-GUI (CLI) programs which are linked with
     'gnustep-base' and installed in '/usr/bin' (or '/usr/games' if it
     is a console-based game).  Tools which are written in the C
     programming language and use 'gnustep-make''s 'ctool.make' also
     fall in this category.

     The package for a single tool should match the tool name.  It
     shouldn't matter that the tool is written in the Objective-C
     language, C, Perl, Python, etc.  If there is a collision with some
     other package, one of them has to be renamed as usual.

     Good: 'src:unar': 'unar'
     Bad: 'src:mknfonts.tool': 'mknfonts.tool'

     Section: Entirely depends on the tool's purpose--'unar' is
     perfectly suitable for section 'utils' but a GNUstep-specific tool
     like 'mknfonts' should be in section 'gnustep'.

Applications
     The most common case, GUI programs which link with 'gnustep-gui'.
     These are installed in '/usr/lib/GNUstep/Applications', with
     '/usr/bin/Foo' or '/usr/games/Foo' being a symlink to
     '/usr/lib/GNUstep/Applications/Foo.app/Foo'.  Applications may have
     architecture-independent resources which may be split into a
     separate 'arch:all' binary package, or can have bundles
     (extensions) installed under the main app bundle or in the GNUstep
     Bundles directory.

     All applications must have the '.app' suffix in their source
     package and binary package names.(1)  If there are several binary
     packages, they must follow the established convention that is used
     (almost) consistently for other Debian packages (e.g.,
     '.app-common', '.app-data', '.app-sounds' or other name as
     appropriate).  If there is a binary package which is
     architecture-dependent and provides a CLI variant of the program,
     it should not have the '.app' suffix.  If the source package also
     provides a shared library as binary packages, they must follow the
     naming scheme for shared libraries.

     Good: 'src:adun.app': 'adun.app' and 'adun-core'
     Bad: 'src:affiche': 'affiche.app'

     Section: If a particular section is suitable, it should be used.
     For example, 'pikopixel.app' should be in the 'graphics' section,
     'fisicalab.app' in section 'education', 'lusernet.app' in 'news'.
     If no section is appropriate or if the app is basically closely
     related to GNUstep ('gworkspace.app' or 'systempreferences.app'
     being the perfect examples for this), use section 'gnustep'.

Libraries
     Shared libraries must follow all the rules and conventions as
     described in the Debian Policy.  *Note (debian-policy)Shared
     libraries::.  If the library also provides bundles which depend on
     the library's interface (the typical case if the library
     dynamically loads bundles), they must be installed in a versioned
     sub-directory or have a versioned suffix so that installing
     multiple versions of the same library is possible.

     If the library name is unique there is no need to change the source
     package name.  If it is generic or likely to clash with another
     package in the future, prepend 'gnustep-'.  That is, if the
     upstream name of the library is 'Performance', the source package
     name should be 'gnustep-performance'.

     Traditionally, many GNUstep libraries and frameworks append 'Kit'
     to their names, so in most cases it should be sufficient to
     distinguish them from other libraries if the main name coincides.
     Binary package names for shared libraries are enforced by the
     Debian Policy and thoroughly checked by 'lintian', so there is
     little or no room for deviation.

Frameworks
     Frameworks are libraries which can be also dynamically loaded like
     bundles by tools/applications with the 'NSBundle' class, or the
     program may link with them as a shared library.  They are installed
     at '/usr/lib/GNUstep/Frameworks' along with a complex and
     convoluted set of symlinks to make them FHS-compliant.  For the
     purpose of Debian packaging, frameworks are considered shared
     libraries and all rules applying to libraries also apply to
     frameworks.

     Good: 'src:dbuskit': 'libdbuskit0' and 'libdbuskit-dev'
     Bad: 'src:popplerkit.framework', 'addressview.framework'

     Section: As is the practice with shared libraries in Debian, the
     runtime library must be in 'libs' and the package providing the
     headers and the '.so' symlink must be in 'libdevel'.  If there is a
     separate package providing documentation (whether it is a library
     reference or a manual), it should be placed in section 'doc'.

Bundles
     Bundles(2) are shared objects which can be dynamically loaded by
     tools, applications or shared libraries.  Consider them as the
     rough equivalent of dynamically opened plugins/modules that are
     widely spread nowadays.  The rendering part of the 'gnustep-gui'
     library ('gnustep-back') is built as bundles managed by Debian's
     alternatives system.

     A package providing a system-wide bundle should be named
     'src:gnustep-FOO-bundle', with FOO being a descriptive word,
     ideally matching the upstream name.  The binary package name should
     be the same.  Note that this convention does _not_ apply to
     application bundles; they belong to the respective '.app' (or
     '.app-FOO') package.

     Good: 'src:gnustep-cddb-bundle': 'gnustep-cddb-bundle'
     Bad: 'src:cddb.bundle': 'cddb.bundle'

     Section: System-wide bundles are specific to GNUstep so they should
     be placed in the 'gnustep' section.

Services
     Services are special kinds of tools which other running
     applications may use through GNUstep's services facility.  Services
     that are provided by applications can be exposed and made
     accessible with the 'make_services' user tool and deserve no
     special mentioning: they are part of the package that is providing
     the application.  There may be system-wide services which are
     packaged separately and installed at '/usr/lib/GNUstep/Services',
     to be shared among applications.  Services are executables that can
     be accessed by any application via its 'Services' menu; they are
     not shared objects to be dynamically opened like bundles.

     A package providing a global system-wide service must be named
     'src:gnustep-FOO-service', with FOO being a descriptive word,
     ideally matching the upstream name.  The binary package name must
     be the same.  System-wide services are only usable within GNUstep
     so the right section is 'gnustep', regardless of the functionality
     that the service provides.

Themes
     Themes are bundles which use the 'GSTheme' class to change the
     appearance of all GNUstep applications.  They can be compiled or
     architecture-independent (also known as "pixmap themes").

     A package providing a GNUstep theme must be named
     'src:gnustep-FOO-theme', with FOO matching the upstream name.  The
     binary package name must be the same.  Naturally, GNUstep themes
     are strictly GNUstep-specific and should be in section 'gnustep'.

Palettes
     Palettes are also bundles which provide some GUI-related
     functionality, usually for a specific application or certain set of
     applications.

     There shouldn't be a reason to package a palette separately, they
     are typically distributed as part of an application that enhances
     another application.  In any case, should the need arise, a package
     providing a palette should be named 'src:gnustep-FOO-palette'.

   ---------- Footnotes ----------

   (1) Some packages are GUI programs but do not link with the GNUstep
GUI library.  For example, 'oolite' is a game that is a GNUstep package
in the general sense, however it is not a GNUstep _application_ and
should not have the '.app' suffix.

   (2) Note that the term "bundle" is widely used within GNUstep and may
have different meanings depending on context.  For example, a '.gorm'
file (somewhat confusingly, it is actually a directory containing
several files) is also a bundle.  An application with its resources is
also called an "app bundle"; there are other examples as well.