| 1 |
grobian 07/09/23 13:26:54 |
| 2 |
|
| 3 |
Modified: techdocs.xml |
| 4 |
Log: |
| 5 |
Adding some policies on making changes to the ebuilds. |
| 6 |
|
| 7 |
Revision Changes Path |
| 8 |
1.9 xml/htdocs/proj/en/gentoo-alt/prefix/techdocs.xml |
| 9 |
|
| 10 |
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/gentoo-alt/prefix/techdocs.xml?rev=1.9&view=markup |
| 11 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/gentoo-alt/prefix/techdocs.xml?rev=1.9&content-type=text/plain |
| 12 |
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/gentoo-alt/prefix/techdocs.xml?r1=1.8&r2=1.9 |
| 13 |
|
| 14 |
Index: techdocs.xml |
| 15 |
=================================================================== |
| 16 |
RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/gentoo-alt/prefix/techdocs.xml,v |
| 17 |
retrieving revision 1.8 |
| 18 |
retrieving revision 1.9 |
| 19 |
diff -u -r1.8 -r1.9 |
| 20 |
--- techdocs.xml 11 Aug 2007 18:44:04 -0000 1.8 |
| 21 |
+++ techdocs.xml 23 Sep 2007 13:26:54 -0000 1.9 |
| 22 |
@@ -1,6 +1,6 @@ |
| 23 |
<?xml version="1.0" encoding="UTF-8"?> |
| 24 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 25 |
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gentoo-alt/prefix/techdocs.xml,v 1.8 2007/08/11 18:44:04 grobian Exp $ --> |
| 26 |
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gentoo-alt/prefix/techdocs.xml,v 1.9 2007/09/23 13:26:54 grobian Exp $ --> |
| 27 |
|
| 28 |
<guide link="/proj/en/gentoo-alt/prefix/techdocs.xml" lang="en"> |
| 29 |
<title>Gentoo Prefixed Portage Techdocs</title> |
| 30 |
@@ -270,6 +270,85 @@ |
| 31 |
connection between the Prefix tree and the main tree. |
| 32 |
</p> |
| 33 |
</body> |
| 34 |
+ </section><!-- }}} --> |
| 35 |
+ |
| 36 |
+ </chapter> |
| 37 |
+ |
| 38 |
+ <chapter> |
| 39 |
+ <title>Prefix tree developer policies</title> |
| 40 |
+ |
| 41 |
+ <section><!-- {{{ updating --> |
| 42 |
+ <title>Main tree migrations</title> |
| 43 |
+ <body> |
| 44 |
+ <p> |
| 45 |
+ In principle, all ebuilds in the Prefix tree are modified |
| 46 |
+ copies from their versions in the main tree, as used by Gentoo |
| 47 |
+ Linux. This means that each ebuild is copied and hence needs |
| 48 |
+ to be kept in sync with the main tree version. Since ebuilds |
| 49 |
+ in the Prefix tree may have manual modifications (those not |
| 50 |
+ automatically made by <c>eapify</c>), the process of keeping |
| 51 |
+ the Prefix tree in sync with the main tree is not as straight |
| 52 |
+ forward as simply re-copying and re-<c>eapify</c>ing. |
| 53 |
+ Instead, a complex script, <c>eupdate</c> is used to apply the |
| 54 |
+ differences made to an ebuild in the main tree, to the version |
| 55 |
+ in the Prefix tree. Also when new versions of ebuilds are |
| 56 |
+ added to the main tree, the <c>eupdate</c> script derives a |
| 57 |
+ new version in the Prefix tree, based on the differences |
| 58 |
+ between the latest two versions of the ebuilds in the main |
| 59 |
+ tree. This process is called a <e>cross-diff</e>. Both |
| 60 |
+ updating strategies may fail depending on modifications made |
| 61 |
+ to the ebuild in the Prefix tree. In 90% of the cases, both |
| 62 |
+ update strategies apply without problems, and semi-automatic |
| 63 |
+ propagation relies on that to currently merge changes from the |
| 64 |
+ main tree on a daily basis, with a limited investment of time |
| 65 |
+ on (manually) resolving the conflicts. |
| 66 |
+ </p> |
| 67 |
+ <p> |
| 68 |
+ Mainly because manually resolving conflicts is a tedious job, |
| 69 |
+ the main policy in the Prefix tree with regard to |
| 70 |
+ modifications made to the main tree version is sound and |
| 71 |
+ simple: <b>avoid any change that is not strictly |
| 72 |
+ necessary</b>!. This boils down to the following concrete |
| 73 |
+ rules that need to be taken into account. Quoting of |
| 74 |
+ variables is a often confusing job. Underquoting results in |
| 75 |
+ problems when spaces are being used, overquoting is just |
| 76 |
+ unnecessary work. In many cases, the quoting of variables is |
| 77 |
+ done wrong in the main tree ebuilds, hence the problem is also |
| 78 |
+ carried over onto the Prefix tree. Fixing these quoting |
| 79 |
+ problems should <e>not</e> be done, unless this is necessary |
| 80 |
+ to solve a Prefix specific problem, which happens only in rare |
| 81 |
+ cases. Along the same line, adding or removing white space, |
| 82 |
+ indenting, rewriting to make more optimal in execution and |
| 83 |
+ similar changes which are not essentially necessary, should be |
| 84 |
+ avoided. To avoid differences in the <c>Changelog</c> file, |
| 85 |
+ you should <e>not</e> use <c>echangelog</c> when committing |
| 86 |
+ changes to ebuilds that are available in the main tree, and |
| 87 |
+ hence subject to semi-automatic updating. In fact each |
| 88 |
+ <c>Changelog</c> entry added using <c>echangelog</c> makes a |
| 89 |
+ conflict during updating, making the problem even worse. |
| 90 |
+ Don't update the <c>ChangeLog</c>. |
| 91 |
+ </p> |
| 92 |
+ <p> |
| 93 |
+ When changes need to be made, such as adding an <c>epatch</c> |
| 94 |
+ line, or adding a platform specific statement, such as an |
| 95 |
+ configure option, care needs to be taken to try to reduce the |
| 96 |
+ size of the differences introduced. The smaller the |
| 97 |
+ difference, the bigger the chance that semi-automatic updating |
| 98 |
+ succeeds without problems. |
| 99 |
+ </p> |
| 100 |
+ <p> |
| 101 |
+ For files that have no CVS header, and hence cannot be kept in |
| 102 |
+ sync, such as e.g. <c>metadata.xml</c> and many patches in the |
| 103 |
+ <c>files/</c> directory the <c>eupdate</c> command just makes |
| 104 |
+ sure it is equal to the version in the main tree. For this |
| 105 |
+ reason, keep in mind that changes to those files get lost upon |
| 106 |
+ the next run of <c>eupdate</c>. Since this is done almost |
| 107 |
+ daily, the modifications disappear soon enough. Only files |
| 108 |
+ with a CVS <c>$ Header</c><c>:</c> <!-- no-expansion hack ;) --> |
| 109 |
+ (such as ebuilds) can be changed in such a way that the |
| 110 |
+ modifications are not lost. |
| 111 |
+ </p> |
| 112 |
+ </body> |
| 113 |
</section> |
| 114 |
|
| 115 |
</chapter> |
| 116 |
|
| 117 |
|
| 118 |
|
| 119 |
-- |
| 120 |
gentoo-commits@g.o mailing list |
Archives