Differences between revisions 1 and 38 (spanning 37 versions)
Revision 1 as of 2010-12-21 04:19:53
Size: 5050
Comment: Initiate a list of guidelines/hints for derivatives
Revision 38 as of 2021-08-15 21:54:25
Size: 12865
Editor: andrewsh
Comment: use a more conventional notation for manpages
Deletions are marked like this. Additions are marked like this.
Line 14: Line 14:
== Infrastructure ==

We encourage derivative distributions to mention and define their relationship with Debian on the web page that gives information about the derivative distro (usually the about page).

We encourage derivative distributions to use Debian infrastructure and the software that powers Debian infrastructure where possible.

== Repositories ==

For those derivatives that re-use Debian binary packages, add some source packages and modify some source packages, where possible we encourage them to use standard Debian mirrors and add a second repository containing only the source and binary packages that have been added or modified.

For those derivatives that rebuild Debian source packages, add some source packages and modify some source packages, where possible we encourage them to use standard Debian mirrors for the source packages and add a second repository containing only the source and binary packages that have been added or modified. This recommendation may be hard to do and therefore regular source package syncing is an alternative recommendation.

Of course in both cases it is a good idea to run a Debian mirror to ensure source and binary availability. Any exact mirrors of Debian source and or binary packages should be registered with the Debian mirrors list.

If you are copying Debian source packages to your repositories without modifying them, please leave the signatures in place in the .dsc files, do not re-sign them with your own keys.

== Keyrings ==

Please create your own keyring packages instead of patching the Debian keyring packages.

== Releases ==

If your derivative is based on Debian stable releases, please start your release testing process at least when the Debian freeze happens or do regular release testing during the whole Debian release cycle.

When you make a suite/release obsolete and unsupported, please move it out of your regular apt repository and place it on a different hostname (such as archive.example.org) or URL (such as ftp.example.org/archive).

If you have a constant number of releases, please give them suite names which should be aliased/symlinked to codenames. In Debian we use oldstable, stable, testing, unstable and experimental, which are aliased to release names like lenny, squeeze, wheezy, sid and rc-buggy.

== Package deprecation ==

Please remove old packages from your main repository. Should you want to keep them available for users, please move them to a repository solely for old packages (such as snapshot.example.org).

<<Anchor(vendor)>>
== Vendor ==

dpkg has the concept of a 'vendor', derivative distributions should set the dpkg vendor to something other than ''Debian''. To change the vendor you can install a file to {{{/etc/dpkg/origins/example}}} and ensure the {{{/etc/dpkg/origins/default}}} symlinks points to {{{example}}}. Please ensure that the {{{Parent}}} field of your dpkg origins file is set to {{{Debian}}}. For more information about the dpkg vendor concept and implementation please read the [[DebianMan:5/deb-origin|deb-origin(5)]] and [[DebianMan:1/dpkg-vendor|dpkg-vendor(1)]] manual pages.
Line 16: Line 53:
 * Derivative distribution must not be named ''Debian'' :)  * Derivative distributions must not be named ''Debian'' :)
Line 18: Line 55:
 * [[http://www.debian.org/trademark|Current Debian trademark policy]] states: To be fair to all businesses, we insist that no business use the name "Debian" in the name of the business, or a domain name of the business.

* Ongoing work on the [[http://wiki.mako.cc/TrademarkFreedom|Draft of the new Debian trademark policy]] aims to clarify/relax above restriction.  Consult Debian project (DPL? debian-legal?) meanwhile on the concrete case...
 * [[https://www.debian.org/trademark|Current Debian trademark policy]] states: To be fair to all businesses, we insist that no business use the name "Debian" in the name of the business, or a domain name of the business.
   * ongoing work on the [[https://wiki.mako.cc/TrademarkFreedom|Draft of the new Debian trademark policy]] aims to clarify/relax above restriction. Consult the [[DebianProjectLeader]] meanwhile on a case-by-case basis
Line 33: Line 69:
   * /etc/dpkg/origins/default (symlink to distribution information file)
   * /etc/os-release (symlink to /usr/lib/os-release)
   * /usr/lib/os-release
Line 36: Line 75:
 * '''debian-installer'''
   * package root/build/boot/x86/ (branding, references to 'Debian on all the fnumber screens')
   * package root/build/config/local (override various strings)
 * '''debian-cd'''
   * will probably need customisation for the install images.
 * '''synaptic'''
   * uses the debian logo for indicating packages
 * '''software-properties-gtk'''
   * talks about dfsg and debian release (eg, squeeze). don't know if this counts :)
Line 39: Line 87:
 * Any default background images carrying Debian official use logo?
 * '''desktop-base'''
   * GDM / KDM / LightDM (etc) branding
   * Default background (GNOME, Xfce, KDE, etc)
   * GRUB background & theme
   * Plymouth bootsplash
   * ksplash branding
   * Has emblem-vendor and vendor-logos alternatives that can be reused by other packages.

 * '''syslinux-themes-debian'''
   * Debian syslinux branding

 * '''ldm-themes'''
   * ldm theme stuff
Line 45: Line 106:
Rebuilt Debian packages should carry distribution specific suffix to avoid confusion with possibly API/ABI-incompatible original packages provided from Debian archives. Rebuilt Debian packages should carry distribution specific version suffix to avoid confusion with possibly API/ABI-incompatible original packages provided from Debian archives.

When modifying source packages, rename the Maintainer field to XSBC-Original-Maintainer and add a new Maintainer field.
Line 49: Line 112:
Since Debian bug tracking system should not be used directly to report bugs in the derivative distributions, submitted bugreports should not be sent directly against Debian packages. ``reportbug`` could either be switched (see /usr/share/doc/reportbug/README.developers.gz) or patched (please do not forget to make patch generic and submit it to Debian) to use some other bug tracking system/server; alternatively different address to submit reports could be specified per each source package in the Bugs field of source portion in ``debian/control`` file. The appropriate action to take with respect to bug reporting depends on the degree to which your derivative distribution is changing/extending Debian and the ways in which Debian is changed by your distribution. In general reports that are about or are a consequence of your modifications to Debian should be submitted to the maintainers of your derivative distribution for analysis. We encourage derivatives to forward bug reports to the Debian bug tracker after checking that the issues also apply to normal Debian systems.
Line 51: Line 114:
Specific choice among above scenarios depends on the degree to which derivative distribution is changing/extending vanilla Debian system. For example, if the derivative does not introduce heavy reconfiguration of the stock Debian system, nor provides custom builds of non-leaf packages -- it should be sufficient to provide custom Bugs: header fields only in rebuilt/new packages. If some base Debian libraries get customized/rebuilt and/or heavy re-configuration of the default Debian system in place, it is advised that all bugreports get submitted to the maintainers of the derivative distribution first for the analysis either the bug is pertinent to stock Debian, where it should be forwarded by the maintainers in such cases. For distributions that rebuild all binary packages, it is recommended to redirect all bug reports to your distribution's tracker.
Line 53: Line 116:
For distributions that modify core or non-leaf packages (especially libraries), it is recommended to redirect all bug reports to your distribution's tracker.

For distributions that modify configuration in ways that affect other packages, it is recommended to redirect all bug reports to your distribution's tracker.

For distributions that only add new packages and modify leaf packages, it is acceptable to redirect bug reports for new/modified packages to your distribution's tracker.

The reportbug/reportbug-ng programs only support email and debbugs as bug trackers. If you are using another bug tracking system you would need to patch them to support it. Please do not forget to make your patch generic and submit it to Debian. You could also not include them in your distribution and require your users to report bugs via another mechanism.

To redirect all bug reports to your distribution's tracker, you can add a ``Bugs:`` field to the ``/etc/dpkg/origins/<distro>`` file (see the [[DebianMan:5/deb-origin|deb-origin manual page]] for details) or see ``/usr/share/doc/reportbug/README.developers.gz``.

To redirect bug reports only for modified/new source packages, you can add a ``Bugs:`` field to the source portion of the ``debian/control`` file of modified/new source packages.

<<Anchor(usertags)>>
When forwarding bugs you should file the bug on a Debian system so that the bug metadata is correct. You may want to use this set of usertags when forwarding bugs and patches to Debian:

 * User: debian-derivatives@lists.debian.org
 * Usertags:
  * origin-<distro>: set this on all bugs/patches you forward
  * patch-<distro>: set this when forwarding a patch
  * release-<distro>-<name>: set this if you want to indicate that it is related to one of your current or future releases
  * feature-<distro>-<name>: set this if you want to indicate that it is related to one of your planned features
  * transition-<distro>-<name>: set this if you want to indicate that it is related to one of your planned transitions

<<Anchor(popcon)>>
Line 55: Line 142:
If you want to become the collector of popcon submissions, please do not simply divert popcon submissions from the default ``popcon.debian.org`` to your server. Multiple target popcon servers could be listed in ``SUBMITURLS``. Please ensure that the ``MY_HOSTID`` and ``DAY`` variables in ``/etc/popularity-contest.conf`` are random and not the same on each installed system.

Please ensure that popcon remains an opt-in system on your derivative. For pre-installed machines please refer to your internal policies, particularly privacy policies, to decide if popcon should be enabled.

In case your derivative has a large number of users the popcon maintainers may ask you to divert all your submissions to a different site or disable popcon.

If your derivative contains popcon 1.58 or later, it will send the [[#vendor|dpkg vendor field]] in popcon reports. If you are using an earlier versions of popcon, please add a suffix containing your distribution name to the popcon version numbers so that Debian has a way to differentiate popcon submissions by Debian users from submissions by users of derivatives.

If your derivative wants to collect popcon submissions, please do not simply divert popcon submissions from the default ``popcon.debian.org`` to your server. Multiple target popcon servers could be listed in ``SUBMITURLS``. popcon 1.60 and later encrypt submissions to the Debian popcon OpenPGP key, so if you send submissions to your own server you will need to get popcon to use your OpenPGP key. For popcon 1.60 you need to patch popcon but popcon 1.61 introduced a mechanism where you can drop in a config file to add additional servers/keys or override the Debian servers/keys, see the [[https://salsa.debian.org/popularity-contest-team/popularity-contest/raw/master/FAQ|FAQ]] for more details.
Line 60: Line 155:
 * If ``apt`` package in the derivative carries custom suffix (since per se no other distribution-specific information is included in the popcon submissions) it could allow Debian to discover the most popular derivatives and provide some nice statistics of the usage beyond stock Debian
 * Niche packages, which might not be very popular in stock Debian, could be more actively used in a specialized derivative distribution. Having adequate popcon statistic in Debian would guarantee that the package would not be removed from stock Debian, thus offloading maintenance burden on the interested derivative
 * It could allow Debian to discover the most popular derivatives and provide some nice statistics of the usage beyond stock Debian
 * Niche packages, which might not be very popular in stock Debian, could be more actively used in a specialised derivative distribution. Having adequate popcon statistics in Debian would guarantee that the package would not be removed from stock Debian, thus offloading maintenance burden on the interested derivative
Line 63: Line 158:

== Lintian ==

[[Lintian]] is a tool for statically checking packages. It is easy to [[Lintian/Vendors|customise it for derivatives]].

== Contributions ==

Debian is happy that our distribution is a good base for derivatives and we welcome contributions from derivatives as we do for everyone. The most useful kind of contributions are for you to work with us to improve Debian (distribution, community and project), in particular to have your code changes integrated into Debian or directly upstream where applicable. If you or your sponsors want to contribute financial or other donations to Debian, we appreciate that too. You can donate using several methods [[https://www.debian.org/donations|documented]] on the Debian website. We usually use money for hardware purchases, development meetings, the annual [[https://www.debconf.org/|Debian conference]] and other things.
Line 66: Line 169:
 * http://www.debian.org/logos
 * http://wiki.mako.cc/TrademarkFreedom
 * https://www.debian.org/logos
 * https://wiki.mako.cc/TrademarkFreedom
 * https://www.debian.org/reports/patent-faq
Line 70: Line 174:
Derivatives [[Derivatives]]

Translation(s): none


This page outlines aspects to take care while creating a derivative Debian distribution.

For now it is just an outline to collect relevant information which could be formalized later on in the form of Specification.

Intro

Derivative Debian distributions vary in the domains of their specialization, user base, and the scale of modifications/extension they bring on top of vanilla Debian distribution. Therefore, there might not be a strict deterministic set of rules, and rather a set of guidelines could help to decide which actions should be taken by the developers of the derivative distribution to not inflict Debian, and, moreover, benefit from the Debian infrastructure/resources/frameworks where applicable.

Infrastructure

We encourage derivative distributions to mention and define their relationship with Debian on the web page that gives information about the derivative distro (usually the about page).

We encourage derivative distributions to use Debian infrastructure and the software that powers Debian infrastructure where possible.

Repositories

For those derivatives that re-use Debian binary packages, add some source packages and modify some source packages, where possible we encourage them to use standard Debian mirrors and add a second repository containing only the source and binary packages that have been added or modified.

For those derivatives that rebuild Debian source packages, add some source packages and modify some source packages, where possible we encourage them to use standard Debian mirrors for the source packages and add a second repository containing only the source and binary packages that have been added or modified. This recommendation may be hard to do and therefore regular source package syncing is an alternative recommendation.

Of course in both cases it is a good idea to run a Debian mirror to ensure source and binary availability. Any exact mirrors of Debian source and or binary packages should be registered with the Debian mirrors list.

If you are copying Debian source packages to your repositories without modifying them, please leave the signatures in place in the .dsc files, do not re-sign them with your own keys.

Keyrings

Please create your own keyring packages instead of patching the Debian keyring packages.

Releases

If your derivative is based on Debian stable releases, please start your release testing process at least when the Debian freeze happens or do regular release testing during the whole Debian release cycle.

When you make a suite/release obsolete and unsupported, please move it out of your regular apt repository and place it on a different hostname (such as archive.example.org) or URL (such as ftp.example.org/archive).

If you have a constant number of releases, please give them suite names which should be aliased/symlinked to codenames. In Debian we use oldstable, stable, testing, unstable and experimental, which are aliased to release names like lenny, squeeze, wheezy, sid and rc-buggy.

Package deprecation

Please remove old packages from your main repository. Should you want to keep them available for users, please move them to a repository solely for old packages (such as snapshot.example.org).

Vendor

dpkg has the concept of a 'vendor', derivative distributions should set the dpkg vendor to something other than Debian. To change the vendor you can install a file to /etc/dpkg/origins/example and ensure the /etc/dpkg/origins/default symlinks points to example. Please ensure that the Parent field of your dpkg origins file is set to Debian. For more information about the dpkg vendor concept and implementation please read the deb-origin(5) and dpkg-vendor(1) manual pages.

Trademark

De-/Re-branding

Depending on the degree of divergence from the vanilla Debian, it might be necessary to introduce non-functional modifications in the deployed system to eliminate user confusion of the derivative distribution with vanilla Debian

Entry points

Following packages along with corresponding files present users with Debian name upon interaction with the system

  • base-files

    • /etc/issue
    • /etc/issue.net
    • /etc/dpkg/origins/default (symlink to distribution information file)
    • /etc/os-release (symlink to /usr/lib/os-release)
    • /usr/lib/os-release
    • /usr/share/base-files/motd
  • grub-pc

    • /etc/grub.d/05_debian_theme
  • debian-installer

    • package root/build/boot/x86/ (branding, references to 'Debian on all the fnumber screens')
    • package root/build/config/local (override various strings)
  • debian-cd

    • will probably need customisation for the install images.
  • synaptic

    • uses the debian logo for indicating packages
  • software-properties-gtk

    • talks about dfsg and debian release (eg, squeeze). don't know if this counts :)

Artwork

  • desktop-base

    • GDM / KDM / LightDM (etc) branding
    • Default background (GNOME, Xfce, KDE, etc)
    • GRUB background & theme

    • Plymouth bootsplash
    • ksplash branding
    • Has emblem-vendor and vendor-logos alternatives that can be reused by other packages.
  • syslinux-themes-debian

    • Debian syslinux branding
  • ldm-themes

    • ldm theme stuff
  • "Debian official use logo" with "Debian" word has usage restrictions: "This logo or a modified version may be used by anyone to refer to the Debian project, but does not indicate endorsement by the project. "

Packages

Rebuilt Debian packages should carry distribution specific version suffix to avoid confusion with possibly API/ABI-incompatible original packages provided from Debian archives.

When modifying source packages, rename the Maintainer field to XSBC-Original-Maintainer and add a new Maintainer field.

Bug reports

The appropriate action to take with respect to bug reporting depends on the degree to which your derivative distribution is changing/extending Debian and the ways in which Debian is changed by your distribution. In general reports that are about or are a consequence of your modifications to Debian should be submitted to the maintainers of your derivative distribution for analysis. We encourage derivatives to forward bug reports to the Debian bug tracker after checking that the issues also apply to normal Debian systems.

For distributions that rebuild all binary packages, it is recommended to redirect all bug reports to your distribution's tracker.

For distributions that modify core or non-leaf packages (especially libraries), it is recommended to redirect all bug reports to your distribution's tracker.

For distributions that modify configuration in ways that affect other packages, it is recommended to redirect all bug reports to your distribution's tracker.

For distributions that only add new packages and modify leaf packages, it is acceptable to redirect bug reports for new/modified packages to your distribution's tracker.

The reportbug/reportbug-ng programs only support email and debbugs as bug trackers. If you are using another bug tracking system you would need to patch them to support it. Please do not forget to make your patch generic and submit it to Debian. You could also not include them in your distribution and require your users to report bugs via another mechanism.

To redirect all bug reports to your distribution's tracker, you can add a Bugs: field to the /etc/dpkg/origins/<distro> file (see the deb-origin manual page for details) or see /usr/share/doc/reportbug/README.developers.gz.

To redirect bug reports only for modified/new source packages, you can add a Bugs: field to the source portion of the debian/control file of modified/new source packages.

When forwarding bugs you should file the bug on a Debian system so that the bug metadata is correct. You may want to use this set of usertags when forwarding bugs and patches to Debian:

  • User: debian-derivatives@lists.debian.org

  • Usertags:
    • origin-<distro>: set this on all bugs/patches you forward

    • patch-<distro>: set this when forwarding a patch

    • release-<distro>-<name>: set this if you want to indicate that it is related to one of your current or future releases

    • feature-<distro>-<name>: set this if you want to indicate that it is related to one of your planned features

    • transition-<distro>-<name>: set this if you want to indicate that it is related to one of your planned transitions

Popularity Contest

Please ensure that the MY_HOSTID and DAY variables in /etc/popularity-contest.conf are random and not the same on each installed system.

Please ensure that popcon remains an opt-in system on your derivative. For pre-installed machines please refer to your internal policies, particularly privacy policies, to decide if popcon should be enabled.

In case your derivative has a large number of users the popcon maintainers may ask you to divert all your submissions to a different site or disable popcon.

If your derivative contains popcon 1.58 or later, it will send the dpkg vendor field in popcon reports. If you are using an earlier versions of popcon, please add a suffix containing your distribution name to the popcon version numbers so that Debian has a way to differentiate popcon submissions by Debian users from submissions by users of derivatives.

If your derivative wants to collect popcon submissions, please do not simply divert popcon submissions from the default popcon.debian.org to your server. Multiple target popcon servers could be listed in SUBMITURLS. popcon 1.60 and later encrypt submissions to the Debian popcon OpenPGP key, so if you send submissions to your own server you will need to get popcon to use your OpenPGP key. For popcon 1.60 you need to patch popcon but popcon 1.61 introduced a mechanism where you can drop in a config file to add additional servers/keys or override the Debian servers/keys, see the FAQ for more details.

Benefits

  • Debian would benefit from more adequate status on the usage of the work of Debian community
  • It could allow Debian to discover the most popular derivatives and provide some nice statistics of the usage beyond stock Debian
  • Niche packages, which might not be very popular in stock Debian, could be more actively used in a specialised derivative distribution. Having adequate popcon statistics in Debian would guarantee that the package would not be removed from stock Debian, thus offloading maintenance burden on the interested derivative
  • Debian's popcon, unlike some other deployed popcon servers, might provide additional information (e.g. historical data) which might not be exposed on the derivative's popcon website for some reason.

Lintian

Lintian is a tool for statically checking packages. It is easy to customise it for derivatives.

Contributions

Debian is happy that our distribution is a good base for derivatives and we welcome contributions from derivatives as we do for everyone. The most useful kind of contributions are for you to work with us to improve Debian (distribution, community and project), in particular to have your code changes integrated into Debian or directly upstream where applicable. If you or your sponsors want to contribute financial or other donations to Debian, we appreciate that too. You can donate using several methods documented on the Debian website. We usually use money for hardware purchases, development meetings, the annual Debian conference and other things.

See also


Derivatives