GLEP: XXX Title: Default structure and proceses for patches inclusion. Version: $Revision: 1.0 $ Last-Modified: $Date: 2009/02/11 12:09:20 $ Author: Tomáš Chvátal <scarabeus@gentoo.org>, Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 11 Feb 2009 Post-History: 14-Aug-2003

Credits

The reasons and ideas for this GLEP are heavily inspired by Debian patch tracking system.

Abstract

Dealing with patches reasonably for easy reviewing and tracking upstream.

Motivation

With simple and standardised directory structure and patch naming conventions, there would be easy way to create patch tracking system which might allow us to share patches with other distributions and upstream. Also it will ease patch inspections and reviews due to easier "on first look" determination what is patch for.

Specification

When we deal with patches we can cross 4 different types of them when packaging.

  1. Upstream patches This patches have to be included in upstream SCM so upstream actually applied them for the next release probably, so they are needed only for the current version of the package.
  2. Distribution patches Patches are not applied by upstream, they might be tracked on upstream bugtracking system. Or the patches are really distribution specific (eg. setting default font type for application).
  3. Baselayout script This is special category where belongs our conf.d/ and init.d/ scripts. They might be used by anyone else actually using the OpenRC.
  4. Various scripts we add as enhancements These are for example default startup configurations and other simple scripts easing usage of the package.

We will have to define default directory structure, and naming conventions for files in those directories.

Directory structure

The directory structure must reflect the state of the above categories and must be still kept simple:

System Message: ERROR/3 (patches-glep.txt, line 65)

Unexpected indentation.
+-kdelibs/
  |
  +-files/
    |
    +-dist/
    |
    +-init/
    |
    +-script/
    |
    +-upstream/
      |
      +-4.1.3/
      |
      +-4.2.1/

Here we can see that in this fabricated kdelibs package we have some distribution patches, init scripts, some normal scripts and even upstream patches for version 4.1.3 and 4.2.1.

Folders should be created and exist only if they contain some files. There is no need to keep the directory structure for empty folders.

Versioned directories should be added only for the upstream patches, because in other cases we don't know if the patch will be needed in the future.

There should be also no files directly in directories files and upstream. For the files directory there might be some exceptions but in most cases there should be NO files.

Naming conventions

Init scripts
These files should be named as ${PN}.initd and ${PN}.confd.
Downstream patches
These files should track bug number and short explanation::
25542-fix_minimal_font_size.patch

Also the patch itself should have in its content some long explanation about what is going on:

System Message: ERROR/3 (patches-glep.txt, line 108)

Unexpected indentation.
# This patch fixes upstream smallest font choice from 4 to 8 pts.
# Created by Tomas Chvatal <i-like@my-mail.org>
# Verified by Jorge Manuel B. S. Vicetto <he-like@his-mail-too.org> #this line is optional.

diff -urN a/app/src/font_size.c b/app/src/font_size.c
...
Upstream patches

These files should track upstream commit number and short explanation:

System Message: ERROR/3 (patches-glep.txt, line 118)

Unexpected indentation.
9a7f9abf569-fix_library_detection.patch

These patches dont need the explanation of what they does in the files but reason for their addition must be explained in Changelog/commit message.

Scripts

These files dont need some special naming convetion there is only need to add bug number to their name. So we can track where it came from:

System Message: ERROR/3 (patches-glep.txt, line 127)

Unexpected indentation.
554-autologin.sh
Also there must be some description in the file itself::
# This script allows us to call autologin instead of prompting the # user for the password. # Created by Tomas Chvatal <i-like@my-mail.org> #!/usr/bin/env bash ...

Future usage

When this glep gets implemented in the tree we can create web service that will show up what patches are used for what and enable quick searching and sorting among them.

Backwards Compatibility

This GLEP does not break any previous compatibility, only patches which are not using it as reference wont be listed on the patch tracking system.