Maintaining XX 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. 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.
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.
It's a good idea to know who's involved in X. When known and applicable, IRC nicks are after their names.
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. 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:
Also classify the priority. The basis for this is:
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. 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. 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. 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. 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. 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.
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:
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. 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:
|
|