Contributing

A few notes, beyond the advice in the excellent devmanual, that should be taken in to consideration when contributing to this overlay.

Package naming

The devmanual’s suggestion that filenames should not contain uppercase characters only causes complex PN/P rewriting or duplication, and as such is ignored in this overlay.

Commit messages

Commit messages should be of the form [<pkg>] <summary>, or simply <summary> for commits that aren’t bound to a single package.

Try to follow Tim Pope’s excellent commit message advice. There is some leeway on the length of the summary to take in to account the package prefix, but beyond that the rules make perfect sense here.

Note

Occasionally I forget or mis-step on the above rule, and from today(2013-04-05) I’ll owe you a coffee every time you point out an infraction. Take advantage, it is the only way I’ll learn!

Patches vs sed

It is common practice in Gentoo repositories to fix minor problems using sed, presumably because it appears to be quick and easy. This type of usage is banned in this overlay. Some of the reasons for this policy are:

  • It is very easy to mis-apply transformations
  • It is very easy for transformations to not be applied at all without anyone noticing
  • For people with poor knowledge of sed it leads to horrendous use of grouping and back-references
  • Well written, correctly addressed, sed expressions tend to be hard for people with only a basic knowledge of the s command to comprehend(far harder than unified diff output)
  • Many people seem to misunderstand what the common sed || die construct does, leading to a false sense of safety. [And frankly, if your die calls are triggered because of missing or mispelt files there are much greater problems than a poorly defined call to sed.]

Note

Users inside the AST firewall often rely on our sed wrappers to alert them of broken sed usage, and that process isn’t changing. I’m not applying this rule to all the overlays I maintain, just ones for external users.

die usage

There are few differences between how die is commonly used in the upstream tree, and how it is used in this overlay. The rules in the overlay aren’t always strictly enforced, but documenting this will hopefully reduce the number of usage questions I’m asked.

do* and die

It is common practise within the main Gentoo repository that calls to the likes of dodoc or doman do not call die on failure. This is not acceptable in this overlay.

Usage of wildcards in calls to do* is also frowned upon, but not enough to clean up previous usage [yet].

All entities that should be installed should raise a failure if they are not installed, there is no middle ground for some specific types of files.

HOMEPAGE usage

Against the advice given in the ebuild variables section of the devmanual, you should feel free to refer to variables in the HOMEPAGE definition.

Even within the upstream repository this advice is seemingly ignored at will, as it serves little purpose.

RESTRICT usage

All usage of RESTRICT in an ebuild should be accompanied by an explanation of the reason for the restriction. It should be obvious to someone looking at an ebuild the reason why tests, for example, are blocked for a given package.

Of course, it is preferable to fix the underlying reason for needing a RESTRICT definition, especially in the case of test and userpriv restrictions.

stabilisation.rem

support/stabilisation.rem is a remind compatible data file that contains the best case stabilisation dates for packages. When a new arch keyword is added, or a package receives a version bump, this file is updated to reflect the earliest possible time a package can migrate to stable.

The format is simple enough:

REM <|stable_date|> *1 MSG %"Stabilise |arch| |CPV|%" %a

Note

The initial stable date value is 30 days in the future, although it can be longer if more testing is likely to be necessary.

package.mask

The profiles/package.mask file includes special syntax for generating removal reminders for packages. An example should explain it adequately:

# James Rowe <jnrowe@gmail.com> (27 Jan 2011)
# Better alternatives available including busybox's fbsplash, plymouth, ksplash
# and many others.
# X-Removal: 2011-02-26
media-gfx/psplash

The format is identical to that defined in portage(5) with the addition of the X-Removal tag that is used by the support/gen_removal.py script to create an remind compatible data file.

A simple, but important, extension that makes it easier to keep on top of important admin tasks.

distutils-r1.eclass usage

When using the PYTHON_COMPAT functionality from distutils-r1.eclass it is important to state the reason why a certain Python version isn’t supported.

This should, in theory, make it easier to track updates. Also, it should make it immediately clear how much work is required to support a specific Python version if the need arises.

A simple example from the ebuild for rad would be:

# 2.5 is restricted due to except...as syntax
# 3.x is restricted due to print command
PYTHON_COMPAT=(python2_{6,7})

You should feel free to use nested brace expansion and sequence expressions in the PYTHON_COMPAT declaration, it makes for far more readable definitions than either of the methods preferred upstream. Compare upstream’s colorama package:

PYTHON_COMPAT=( python2_5 python2_6 python2_7 python3_1 python3_2 )

or upstream’s pep8 package where brace expansion is used:

PYTHON_COMPAT=( python{2_5,2_6,2_7,3_1,3_2,3_3} )

with the preferred style for this overlay using flake8 as an example:

PYTHON_COMPAT=(python{2_{5..7},3_{1..3}})

distutils.eclass usage

Important

At this point you should not be using distutils.eclass for ebuilds, use distutils-r1 for all new packages and upgrade packages when bumping.

When using the RESTRICTED_PYTHON_ABIS functionality from distutils.eclass it is important to state the reason why a certain Python version is restricted. See distutils-r1 for more information.

A simple example from an old ebuild for rad would be:

SUPPORT_PYTHON_ABIS="1"
PYTHON_DEPEND="2:2.6"
# 2.4 is restricted due to relative imports and except...as syntax
# 2.5 is restricted due to except...as syntax
# 3.x is restricted due to print command
RESTRICT_PYTHON_ABIS="2.[45] 3.*"

watch files

Each package directory contains a watch file that is used to generate support/cupage.conf. The support/cupage.conf file is a config file for cupage, which helps us to keep up with new package releases by automating the process of checking project sites.

The format is basically quite simple, but there are a few caveats. First, an easy example from www-client/cupage:

site = github
user = JNRowe

This configuration is all that is needed to check for new tags in the JNRowe/cupage project on GitHub.

The output of cupage.py --list-sites shows all the possible definitions for the site option. If the upstream project is located on one of those sites then the watch file should be extremely simple.

For projects not using one of cupage‘s supported sites a manual matcher must be built. An example from dev-python/astral should be quite illustrative:

url = http://www.sffjunkie.co.uk/python-astral.html
select = td a
match_type = zip

This tells cupage to check the defined URL for a tags that are descendants of td tags, and whose href attributes appear to match zip file names.

For more information about configuring cupage visit the cupage documentation.

Caveats

If the package name does not match the project name then the project name must be specified in the watch file. A live example from this repository would be dev-python/straight-plugin:

[straight.plugin]
site = pypi

Note

Project names are almost always case-sensitive, and project names must be specified when the package and project names differ as in the example above.

For a live ebuild, or an upstream that has since disappeared, where using cupage is unworkable a special entry should be placed in a package’s watch file.

For a live ebuild add the string # Live ebuild to the start of the file. It is possible to add other information to the end of the file.

For a package where the upstream site is dead add the string upstream is dead somewhere in the watch file. It is possible to add informative notes to the file, such as the previous location or package author data.