diff options
Diffstat (limited to 'xml/htdocs/proj/en/gentoo-alt/contribute/overlay.xml')
| -rw-r--r-- | xml/htdocs/proj/en/gentoo-alt/contribute/overlay.xml | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/xml/htdocs/proj/en/gentoo-alt/contribute/overlay.xml b/xml/htdocs/proj/en/gentoo-alt/contribute/overlay.xml new file mode 100644 index 00000000..a3624b39 --- /dev/null +++ b/xml/htdocs/proj/en/gentoo-alt/contribute/overlay.xml @@ -0,0 +1,183 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gentoo-alt/contribute/overlay.xml,v 1.3 2006/05/02 06:33:54 flameeyes Exp $ --> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> + +<sections> + +<version>1.1</version> +<date>2005-12-15</date> + +<section> <!-- The overlay --> +<title>The Overlay</title> + +<subsection> <!-- Reasoning --> +<title>Reasoning behind</title> +<body> + +<impo> +This guide is still a <e>draft</e>. It does not contain true policies about the +use of the overlay as they are not being delineated yet, +</impo> + +<p> +Gentoo/Alt projects often need to change current ebuilds to let them know about +their userland, libc or what else. These changes can be non-trivial, and should +usually be hold until the maintainer of the ebuild can take a look to the +patches and make sure that they works as intended. +</p> + +<p> +The drawback is that then Gentoo/Alt users can't make use of the ebuilds on the +fly, and developers might try to do the same thing more than one time as they +might not know what the other developers worked on. +</p> + +<p> +The overlay idea is took from Gentoo/FreeBSD, that used the overlay to apply +patches that involved, for example, malloc patches, userland checks and other +things that should have been reviewed before going into main tree. +</p> + +</body> +</subsection> + +<subsection> <!-- In and Out --> +<title>In and Out</title> +<body> + +<p> +The overlay is intended to work as a cache of ebuilds while they are being +tested (for totally new packages) or while the patches are being reviewed by +ebuild maintainers. +</p> + +<p> +In the case of packags that goes on the overlay just to wait for review +by ebuilds maintainers, their addition should be direct, with obviously the +same name of the original package. It's usually better, if the patch is +trivial, to open a bug and note that in the ChangeLog for the overlaid package +just before adding the package to the overlay itself, unless the patches needs +to be tested for a while before submitting them to the ebuild maintainer. +</p> + +<p> +As soon as a patch is merged in main tree, the ebuilds in the overlay needs to +go, to avoid having unneeded ebuilds there. It's also important to have the +ebuilds be in sync with the main tree in case of revision bumps. +</p> + +</body> +</subsection> + +<subsection> <!-- Where --> +<title>Where</title> + +<body> + +<p> +For developers, the overlay is available on Gentoo's Subversion repositories in +<path>svn+ssh://username@svn.gentoo.org/var/svnroot/gentoo-alt/trunk/overlay</path>. +It's not restricted, so please don't +go over other's changes without notifying before, unless they causes problem on +all the systems. Always try to get a solution that does work for every project +while changes the minimum quantity of code. +</p> + +<p> +As the overlay is intended to be used by users, too, daily snapshots can be +found on mirrors as +<path>/experimental/snapshots/portage-alt-overlay-latest.tar.bz2</path>. The +daily snapshot can be fetched and used as portage overlay, and should be safe +to be used in both Gentoo/Alt and Gentoo/Linux systems, also if might happen +that the overlay interfere with Gentoo/Linux. In case that happens, remember +to contact Gentoo/Alt developers so that the issues can be checked and resolved. +</p> + +</body> +</subsection> + +</section> + +<section> <!-- Development --> +<title>Development</title> + +<subsection> <!-- Committing --> +<title>Committing</title> + +<body> + +<p> +One of the reasons why Subversion was chosen instead of CVS is that it supports +atomic commits, does not expand keywords (like <c>$Header: $</c>) and +so we can use it without using a two-step commit for manifests. +</p> + +<p> +For this reason, the third line of ebuilds is safe to remain +<c>$Header: $</c> so that it will be safe when it's being moved to +main portage. +</p> + +<p> +When committing, it's important to use <c>echangelog</c>, also if it's an +overlay to state the reasons why the ebuild is being changed. It's simple to +write a bash function to get the commit done at one time: +</p> + +<pre caption="Bash function to commit to Subversion"> +svncommit() { + [[ -n $(echo *.ebuild) ]] && { echangelog "$@" } + ebuild $(ls *.ebuild | head -n 1) manifest || return 1 + svn ci -m "$@" || return 1 +} +</pre> + +<p> +Repoman still has a couple of issues when used in overlays, especially with +Subversion, and with extra categories, as it's being done on Gentoo/Alt, but +these things can be easily fixed in the future, and are just side problems. +</p> + +<p> +<c>echangelog</c> still does not support Subversion-reposited ebuilds, so +until it supports them fully, its output will be a bit limited, not telling +when files are added and when are removed. It also returns a failure error +to the caller, so it can't be checked against for failures. +</p> + +</body> +</subsection> + +<subsection> <!-- Distfiles --> +<title>Distfiles</title> + +<body> + +<p> +Because ebuilds in the overlay are public to the users, their distfiles should +be present in the mirrors. As the overlay ebuilds are not parsed by mirroring +scripts, the distfiles loaded directly into the local +<path>dev.gentoo.org</path> distfiles directory will be removed when "dead" +distfiles are removed. +</p> + +<p> +To avoid having the distfiles removed, especially for tarballs that was created +ad-hoc, it's important to whitelist the extra files. To do so, log into +<path>dev.gentoo.org</path> and open the +<path>/space/distfiles-whitelist/current</path> file. There, place one by line +all the files you put or are going to put in the mirrors that should not be +removed. The whitelist lasts for six months. +</p> + +</body> +</subsection> + +</section> + +</sections> + +<!-- kate: space-indent on; indent-width 2; replace-tabs on; --> |