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' 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 category belong in DEPEND, and packages containing fonts, libraries and executables should go in RDEPEND. already pre-populates the dependencies based on heuristics to determine the package type (driver, library, etc.)

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  (earliest version to which the patch is applied) followed by a meaningful short description or  -like filename.

How to Apply Them
Use the functions and variables that provides, namely PATCHES and XORG_EAUTORECONF (for patches which touch  or ). Please do not call or  directly.

Upgrades
Thanks to, 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, 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 file that you can use for testing  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 and use this command to get the list:

Dedicate the time to fully understanding how 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 script from the Gnome overlay. It can be fed the list of x11 maintained packages generated with the 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: