Project:X11/Ebuild maintenance

Maintaining Modular X.org Ebuilds

Dependencies

The modularization of X doesn't allow components of X to safely assume everything they need will be present at both build- and run-time. Modular packages' configure.ac is useful for finding out what upstream thinks is required and is a good guide for what your resulting ebuild should require. Most of this information is held within the PKG_CHECK_MODULES lines (note that there are often multiple - look through the whole file).

As a general (and somewhat obvious) rule of thumb, packages from the x11-proto category belong in DEPEND, and packages containing fonts, libraries and executables should go in RDEPEND. xorg-2.eclass already pre-populates the dependencies based on heuristics to determine the package type (driver, library, etc.)

Patches

Where to Find Them

Patches you'll add will come from basically two places: Gentoo's Bugzilla and freedesktop.org's Bugzilla. They may link to other places from there, but don't feel any pressure to go out patch-hunting beyond those Bugzillas and the X mailing lists.

When to Accept Them

Patches should only be added after there has been an upstream bug filed and the patch has been accepted upstream. This ensures that the code benefits from review by the most experienced people in the field and reduces the burden of support on us, because we can start pointing problems upstream. It also makes things easier on us in the future, because the next release will have the patch included so it can be dropped from our patchset.

Strictly avoid to accept any requests to add random patches to our ebuilds, regardless of their source, unless they are also in upstream. If somebody already filed an upstream bug, follow that bug through until the patch is committed (or at the very least, received a "looks good to me" from the relevant upstream maintainers) before adding it to our patchset. If you accept a patch that has not been committed upstream, you declare to be personally ready to carry the maintenance burden for the patch indefinitely.

The only exceptions to this rule are when the patch fixes a build breakage or a security vulnerability, or cannot be used by upstream because it is for some reason Gentoo-specific.

How to Format and Name Them

Above the content of each patch, make sure that it comments on what the patch does and why it is necessary. If the patch was taken from upstream git, you can keep the original messages. If taken from elsewhere, make sure there is an upstream bug filed for every such patch added to the tree, and make sure this URL is listed in the top of the patch.

It is suggested to prepend the patch name with ${P} (earliest version to which the patch is applied) followed by a meaningful short description or git format-patch -like filename.

How to Apply Them

Use the functions and variables that xorg-2.eclass provides, namely PATCHES and XORG_EAUTORECONF (for patches which touch configure.ac or Makefile.am). Please do not call epatch or eautoreconf directly.

Upgrades

Thanks to xorg-2.eclass, many upgrades are just a rename of the ebuild. If a live ebuild in the portage tree or x11 overlay exists, make any necessary dependency or other changes there first, then copy the ebuild into your local portage checkout.

To find the packages which need upgrades, use either the python script x-modular-bumpchecker.py, which you can find in the gentoo-bumpchecker git repository or visit the euscan website. Also you can subscribe to the xorg-announce mailing list to receive notifications of latest package releases.

The following command will generate a list of packages that can be viewed in your browser, and also a package.accept_keywords file that you can use for testing ~arch packages on stable systems:

user $python x-modular-bumpchecker.py -k -o vystup.html

(Output will be nicely formatted if gbc.css is in the same directory)

More stuff relevant to modular maintenance

Definitely have a list of every modular package so you can script actions across all of modular X. Without this, it can take forever to get anything major done. Even with it, major cross-tree commits take a ton of time. Install sys-apps/pkgcore and use this command to get the list:

user $pquery --maintainer x11 --repo /var/db/repos/gentoo --no-version | tee file

Dedicate the time to fully understanding how xorg-2.eclass works because it will pay off when you get tricky bugs, or when you want to make a change to how something builds.

Some useful links are the Autobook, the Modular Developer's Guide, and the devmanual section on autotools.

Stabilization

In order to keep arch teams happy, stabilization is recommended to happen in batches. Create a stabilization bug and attach a list of packages which are long enough in the tree with no serious regressions. For major/minor version upgrades it is suggested to wait the usual 30 days. For patch level version upgrades, this period can be shorter.

To generate a list of packages for stabilization, use the gen_archlist.py script from the Gnome overlay. It can be fed the list of x11 maintained packages generated with the pquery command from above.

In the stabilization bug, mention the command which allows arch teams to generate a package.accept_keywords file for their particular arch:

# awk '/YOURARCHHERE/ {print "="$1}' x11_stable.list > x11_stable.keywords

---

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Donnie Berkholz, Chi-Thanh Christopher Nguyen
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.