Skip to content

Discussion: NeuroDebian patches processing

NeuroDebian patches apply on top of conventional Debian packaging and are used to differentiate ND packahe, fix build failures specific to NeuroDebian environment etc.

Current Implementation

According to paragraph 3.3 of NeuroDebian Policy, ND-specific patches are located in debian/patches/neurodebian directory of the package.

As per proposed implementation in NeuroDebian Bot, current structure of ND folder is as follows:

<package-root>/debian/patches/neurodebian:
  - patches-to-add
  - patches-to-remove
  - sed-patterns
  - patch1.patch
  - patch2.patch
  - …

where patches-to-add and patches-to-remove are quilt(1) series files denoting one patch name per file.

The processing script reads them and modifies the debian/patches/series as follows:

  • Every file mentioned in patches-to-add is appended to seriesfile with # Added by NeiroDebian Bot comment
  • Every file mentioned in patches-to-remove is commented out from seriesfile with # Removed by NeuroDebian Bot comment

so that the the package like:

debian/patches/series:

0001-normal.patch
0002-patch-to-be-excluded-from-nd.patch

debian/patches/neurodebian/patches-to-add:

0003-patch-to-be-included-in-nd.patch

debian/patches/neurodebian/patches-to-remove:

0002-patch-to-be-excluded-from-nd.patch

gets the resulting debian/patches/series file like:

0001-normal.patch
# Removed by NeuroDebian Bot: 0002-patch-to-be-excluded-from-nd.patch
neurodebian/0001-patch-to-be-included-in-nd.patch # Added by NeuroDebian Bot

NeuroDebian patch tree and Git branch

Current implementation requires having the separate copy of debian/patches/neurodebian directory in each NeuroDebian Git branch (neurodebian/sid, neurodebian/trixie etc).

Pros:

  • Simple to transform patches

Cons:

  • Maintainer's manual work needed to update all ND Git branches in case ND vendor patch is added/removed

Alternative approach is to make changes into debian/patches/neurodebian directory only in primary Git branch (i.e neurodebian/sid) and propagate its exact copy into backport branches (i.e neurodebian/trixie, neurodebian/bookworm etc).

Pros:

  • Single point of maintainer's intervention

Cons:

  • How does the patch transformer understand which branch it is?

Solution: to introduce debian/neurodebian.conf (similar to debian/gbp.conf) with the gbp.conf-like syntax:

[neurodebian]
packaging-branch = neurodebian/sid
patch-queue-name = neurodebian-sid

and split patches-to-{add,remove} into common and specific-branch queues so that target_queue(branch) = common_queue + branch_queue(branch).

Variants of patches-to-{add,remove}:

  • There is patches-to-add.common and patches-to-add.sid
  • There is single pair of patches-to-{add,remove} and eligible target branches are specified in comment:
Add-common-patch1.patch
Add-common-patch2.patch
Add-sid-only-patch.patch # neurodebian/sid
Add-sid-trixie.patch # neurodebian/sid neurodebian/trixie
  • Combined patches-to-{add,remove} file where patches can be added and removed per-branch:
# +all
Add-common-patch1.patch
# +all
Add-common-patch2.patch
# +neurodebian/sid
Add-sid-only-patch.patch
# +neurodebian/sid +neurodebian/trixie
Add-sid-trixie.patch

Automating the transformation

While NeuroDebian Bot can transform and commit the Debian packaging directory, human ND contributors will often forget to invoke patch transformer tooling after makimg changes to ND directory (and there is no way to remimd them to do so in current Debian workflow!)

Question: is it possible to transform Debian packaging files (debian/{control,patches/series,rules}) before applying patches via dpkg-source(1) and dpkg-buildpackage(1) ?

We can do that by adding new Debian source package class into /usr/share/perl5/Dpkg/Source/V3/Neurodebian.pm

Solution: create a neurodebian-dpkg-dev package providing the new debian/source/format type 3.0 (neurodebian), upload it to ND archives and keep debian/source/format file inside ND branches custom.

Pros:

  • NeuroDebian patches get seamlessly integrated into dpkg workflow just like debian/patches/series
  • Contributors continue using familiar Debian tooling
  • Only one package from ND archive is needed to activate the new package format

Cons:

  • Extension of /usr/share/perl5/Dpkg/Source/V3/Quilt.pm is needed into /usr/share/perl5/Dpkg/Source/V3/NeuroDebian.pm in Perl
  • quilt(1) and gbp(1) know nothing about ND patches

Alternatives explored:

  1. Add import-orig.postunpack command into debian/gbp.conf. Con: works only for gbp-import-orig(1) but not for other gbp / git workflows

  2. Use vendor patch series. Con: Debian CTTE ruling made them forbidden in 2019

  3. Use gbp-pq(1) for NeuroDebian. Con: tooling must be invoked manually

Going fully synthetic branches

Alternative approach is not to mix human and bot contributions into branches and follow Google's way in gvisor:

  1. NeuroDebian directory is stored in neurodebian/maint branch and humans are expected to make changes there.
  2. All target ND branches (neurodebian/sid, neurodebian/trixie, neurodebian/bookworm etc) are synthetic (generated by ND bot) and buildable with vanilla Debian tooling.
  3. Human contributors are informed about contribution rules via debian/README.neurodebian and all non-bot MRs to synthetic branches are discarded.

This approach well extends current bot implementation but several things to consider:

  • Should the copy of scripts be held in neurodebian/maint branch or installing the package from ND archive is better?
    • This is needed only for development, not for building of package - big plus compared to previous solution with dpkg.
    • Pros for all ND-specific script packaged as neurodebian-devscripts: centralized updates, more lightweight ND packaging.
    • Cons for all ND-specific script packaged as neurodebian-devscripts: ability to maintain package with only main Debian archive available (doubtful plus as gbp etc are also needed)
  • The canonical procedure of ND branch maintenance should be documented.
Edited by Vasyl Gello