Gentoo Logo

Maintaining X

Content:

1.  Introduction

X is one of the more complex and critical maintainer's jobs. There's a lot to figure out before one can do it properly. This guide attempts to lead a new X maintainer down one path to keeping sanity.

2.  Preparation

Mailing Lists

The first thing to do is to get in contact with upstream. One of the pathways is mailing lists. You'll probably want to subscribe to all of these.

List Description Where/How to Subscribe
xorg@lists.x.org Primary X.Org list -- users and devs http://lists.x.org/mailman/listinfo/xorg/
xorg-commit@lists.x.org CRITICAL to be on this list http://lists.x.org/mailman/listinfo/xorg-commit/
xorg-announce@lists.x.org (Optional) X.org related announcements, mostly of new releases http://lists.x.org/mailman/listinfo/xorg-announce/
dri-devel@lists.freedesktop.org (Optional) DRI (Direct Rendering Infrastructure) -- i.e., 3D acceleration http://lists.freedesktop.org/mailman/listinfo/dri-devel
mesa-dev@lists.freedesktop.org (Optional) X uses this graphics library for OpenGL http://lists.freedesktop.org/mailman/listinfo/mesa-dev
mesa-commit@lists.freedesktop.org (Optional) Follow 3D driver, libGL development http://lists.freedesktop.org/mailman/listinfo/mesa-commit/

IRC Channels

A great medium for generating some camaraderie with upstream and other packagers is IRC. Making connections is a good way to get things accomplished. Unless specified otherwise, all these are on irc.freenode.net.

Channel Description
#xorg-devel Developer-centered channel
#xorg (Optional) More user-oriented, although some devs are here too
#dri (Optional) DRI user channel
#dri-devel (Optional) DRI development channel -- if you like 3D, be here
#ati (Optional) Mostly talk about the binary drivers, but some DRI mixed in
#nvidia (Optional) Talk about the binary drivers
#intel-gfx (Optional) Talk about the Intel open source drivers
#radeon (Optional) Talk about the Radeon open source drivers
#nouveau (Optional) Talk about the Nouveau open source drivers

Who's Who in X Land?

It's a good idea to know who's involved in X. When known and applicable, IRC nicks are after their names.

Who? IRC Nick? What?
Dave Airlie airlied DRM maintainer. Merges DRM into Linux kernel as well. Hacks some on EGL.
Stuart Anderson anderson X.Org guy. He's on IRC, but I've never seen him say anything. Works for The Open Group and is involved with XTest.
Eric Anholt anholt Jumped into X in the past couple of years. Mostly does DRI, radeon stuff. FreeBSD X maintainer, now works for Intel on its driver.
Alan Coopersmith alanc X guy at Sun. Wrote the IPv6 code. Release manager for 6.9.
Michel Daenzer MrCooper Debian X guy and radeon PPC DRI dev, now works for Tungsten Graphics.
David Dawes Lead of XFree86. He's called himself various titles over time, but he's always been the dictator.
Alex Deucher agd5f Hacks on dual-head, Radeon, Savage, and some other misc. stuff
Thomas Dickey Maintains xterm, does some other misc. X and ncurses stuff.
Egbert Eich egbert SuSE X maintainer, X.Org board member. Was release manager for 6.7.0.
Jim Gettys jg keithp's partner in crime
Matthieu Herrb herrb OpenBSD X maintainer. Many commits are security-related, so watch them.
Benjamin Herrenschmidt benh Works for IBM. Hacks some on Radeon, particularly PPC.
Kristian Hogsberg krh Works for Red Hat. Hacked on evdev driver, helped in modularization
Alan Hourihane alanh Maintains i915 driver, trident driver. Has hacked on sunffb DRI too.
Adam Jackson ajax DRI, dlloader, and general server cleanup. He uses Gentoo and will help out. He's on the x11 alias. Release manager for 7.0. Red Hat X maintainer.
Dave Jones davej Maintains agpgart in Linux kernel
Nolan Leake nolan Works for VMWare, maintains vmware driver
Roland Mainz nrubsig Develops XPrint. Been very scarce for the last year or so.
Kevin Martin kem Works for Red Hat. Release manager for 6.8.0, 6.9/7.0.
David Nusinow gravity New Debian X maintainer
Keith Packard keithp A leader of the "new wave" of X developers, works at Intel
Brian Paul Mesa maintainer
Aaron Plattner AaronP Works for nVidia. Maintains nv driver in XOrg.
Ian Romanick idr Works for IBM. DRI guru.
Zack Rusin zrusin Works for Trolltech. Did some work with Exa and Render.
Søren Sandmann ssp Works for Red Hat. Did some MMX optimization, modularization work.
Daniel Stone daniels Lots of experience in modularized, autotooled X. Now works at Nokia, former Ubuntu and Debian X maintainer.
Luc Verhaegen libv Hacks on via driver
Mark Vojkovich Works for nVidia. Maintains nv driver in XFree86.
Keith Whitwell keithw A lead DRI developer, along with idr.

3.  Handling Bugs

Queries

Before you can start dealing with bugs, you need to have good ways to find which ones you want to deal with. I have 10 X-related queries saved in my Bugzilla settings: X Security, X blocker, X critical, X major, X minor, X trivial, X inclusion, X CC, X and X enhancements. The X query is: All bugs with Status UNCONFIRMED NEW ASSIGNED REOPENED where severity is everything except enhancement and bug owner is x11@gentoo.org. The X enhancements query is the same but with the severity set only to enhancement. Similar holds true for other severity-related queries. X CC is all open bugs that x11@gentoo.org is CC'd on. X inclusion is all open bugs assigned to x11@gentoo.org with Keywords: Inclusion. This is used to create a short list of ready-to-go commits with attached patches or very obvious changes. X Security is a list of all open bugs with either assignee or CC x11@gentoo.org and either assignee or CC security@gentoo.org.

You may wish to divide the bugs up better, but first realize this: Bug priorities are not well-triaged at this point in time (2 May 2007), so restricting the priority is a very artificial way to do things. After you enter this search into the advanced page, you'll be able to save it from the bottom of the results page.

Triage

As soon as you have time after reading your Bugzilla emails, you should go to the bug URL and glance briefly over the bug. In this time, you should be able to figure out whether: (a) the bug is assigned to the right people, (b) any other people should be CC'd, (c) the bug is not obviously invalid and (d) the system isn't overoptimized. From (d), it follows that you'll need emerge info to diagnose the problem in nearly all cases, so you get CFLAGS and the toolchain.

If the bug appears valid and should be assigned to us, then classify the severity. The basis for this is:

Severity Description
blocker It breaks entire systems, causes data loss, prevents booting, etc.
critical Compilation failures that don't appear to be corner cases, unavoidable crashes, X not starting
major Significant runtime issues that render X useless
normal Most bugs will fall under this.
minor Bugs that don't significantly affect use and have a workaround
trivial Bugs that result in nearly no end-user or developer change. For example, prettifying some code in the ebuild, small docs typos, etc.
enhancement Feature requests, new packages, etc. Version bumps do not fall under this. They should probably be "normal."

Also classify the priority. The basis for this is:

Priority Description
P1 Must-fix
P2 Might-fix
P3 Probably won't fix
P4 Won't fix unless there are no other open bugs and nothing else to do
RESOLVED->WONTFIX Won't fix, period

Bug-fixing

Once you've got all the open X bugs triaged, you can start fixing them. It's vital to remember that you need to split your time between all levels of severity. There will always be more critical bugs coming in, and if you never work on anything lower unless there are no critical bugs, you'll never work on anything lower. You don't need to split your time evenly -- just split it.

Just start looking through all priority-1 bugs. Ignore anything priority-2 and lower until all priority-1 bugs are fixed. Always be alert for mis-classified bugs while you're browsing the list of open bugs, whether they're over- or under-prioritized. The same goes for severity.

Open a bug and glance through it. Does it have all the necessary info? You'll often need /etc/X11/xorg.conf, /var/log/Xorg.${DISPLAY}.log, emerge info and dmesg. First, make sure the user has a proper configuration. Then, make sure the USE combination is known to work. For example, right now, combining dmx and doc breaks the build. One of my favorite little commands is grep -e '^(EE)' -e '^(WW)' Xorg.0.log. If it's a problem with direct rendering, you'll often want LIBGL_DEBUG=verbose glxinfo output.

After requesting more information from the users, close their bugs as RESOLVED->NEEDINFO and ask them to reopen it upon reply. This ensures that all open bugs are bugs that require action from the X11 team.

If it's a bug with the X code rather than our ebuilds, the reporter needs to send it upstream. Ask them to file it in the xorg product at bugs.freedesktop.org and post the URL in the Gentoo bug, then reopen the bug when it's been committed upstream. Close the bug as RESOLVED->UPSTREAM and add the upstream URL to the URL field.

4.  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 can only be added after there has been an upstream bug filed and the patch has been committed 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.

Never 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 before adding it to our patchset.

The only exceptions to this rule are when the patch fixes a build breakage or a security vulnerability.

How to Format Them

Try to format patches to apply from the directory one level above ${S}. For example, a libX11-1.0.0 patch would diff from libX11-1.0.0.orig to libX11-1.0.0, using diff -urN libX11-1.0.0.orig libX11-1.0.0 > patchname.patch. If you're creating the patch from upstream source code, it may be easier to apply from within ${S} instead. Don't waste any effort on remaking that patch, although you can do this using filterdiff --addprefix from patchutils.

Above the content of each patch, add comments on what the patch does and why it is necessary. Make sure there is an upstream bug filed for every patch added to the tree, and make sure this URL is listed in the top of the patch. The only exception is a patch that cannot be used by upstream because it is for some reason Gentoo-specific.

5.  Maintaining Modular

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, x11-proto/* packages belong in DEPEND, and packages containing fonts, libraries and executables should go in RDEPEND. See the modular X porting guide for details.

Upgrades

Thanks to xorg-2.eclass, many upgrades are just a rename of the ebuild. If a live ebuild in the 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 the python script x-modular-bumpchecker.py, which you can find in the gentoo-bumpchecker git repository at git.overlays.gentoo.org/proj/gentoo-bumpchecker.git.

Code Listing 5.1: Checking for packages that need upgrade

(Output will be nicely formatted if gbc.css is in the same directory)
# python x-modular-bumpchecker.py -k -o vystup.html

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

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 pkgcore and use this command to get the list:

Code Listing 5.2: Get a list of x11 maintained packages

# pquery --herd x11 --repo /usr/portage --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 at git.overlays.gentoo.org/proj/gnome.git. 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.keywords file for their particular arch:

Code Listing 5.3: Generate package.keywords from stabilitation list

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


Print

Page updated 12 December 2011

Summary: This document outlines what needs to be done to successfully maintain X implementations.

Donnie Berkholz
Author

Chí-Thanh Christopher Nguyễn
Editor

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.