| 1 |
commit: c53815c1e8d2ff18bc0dbd7932220d52c60d98b4 |
| 2 |
Author: Markos Chandras <hwoarang <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Sat Nov 3 21:47:55 2012 +0000 |
| 4 |
Commit: Markos Chandras <hwoarang <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Sat Nov 3 22:03:59 2012 +0000 |
| 6 |
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=c53815c1 |
| 7 |
|
| 8 |
ebuild-maintenance: Add cvs and other portage rules from devrel hb |
| 9 |
|
| 10 |
--- |
| 11 |
ebuild-writing/ebuild-maintenance/text.xml | 139 ++++++++++++++++++++++++++++ |
| 12 |
1 files changed, 139 insertions(+), 0 deletions(-) |
| 13 |
|
| 14 |
diff --git a/ebuild-writing/ebuild-maintenance/text.xml b/ebuild-writing/ebuild-maintenance/text.xml |
| 15 |
index 133fe93..3915476 100644 |
| 16 |
--- a/ebuild-writing/ebuild-maintenance/text.xml |
| 17 |
+++ b/ebuild-writing/ebuild-maintenance/text.xml |
| 18 |
@@ -13,6 +13,78 @@ developers may not be familiar with. |
| 19 |
<section> |
| 20 |
<title>Adding a new ebuild</title> |
| 21 |
<body> |
| 22 |
+ |
| 23 |
+<subsection> |
| 24 |
+<title>What (not) to put in the Portage tree</title> |
| 25 |
+<body> |
| 26 |
+ |
| 27 |
+<p> |
| 28 |
+Before writing a new ebuild, check |
| 29 |
+<uri link="http://bugs.gentoo.org/">bugs.gentoo.org</uri> |
| 30 |
+to see if an ebuild has already been written for the package, but has not yet |
| 31 |
+been added to the Portage tree. Go to <uri |
| 32 |
+link="http://bugs.gentoo.org/">bugs.gentoo.org</uri>, choose query and select |
| 33 |
+Advanced Search; as product select <e>Gentoo Linux</e>, as component select |
| 34 |
+<e>ebuilds</e>. In the search field put the name of the ebuild and as status |
| 35 |
+select NEW, ASSIGNED, REOPENED and RESOLVED (RESOLVED is important), then |
| 36 |
+submit the query. For you lazy people, click <uri |
| 37 |
+link="http://bugs.gentoo.org/query.cgi?product=Gentoo%20Linux&component=Ebuilds&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED">here</uri>. |
| 38 |
+</p> |
| 39 |
+ |
| 40 |
+<p> |
| 41 |
+In general, the Portage tree should only be used for storing |
| 42 |
+<path>.ebuild</path> files, as well as any relatively small companion |
| 43 |
+files, such as patches or sample configuration files. These types of |
| 44 |
+files should be placed in the <path>/usr/portage/mycat/mypkg/files</path> |
| 45 |
+directory to keep the main <path>mycat/mypkg</path> directory uncluttered. |
| 46 |
+Exceptions to this rule are for larger patch files (we recommend this for patches |
| 47 |
+above 20KB) which should be put onto the Gentoo mirrors so that people |
| 48 |
+do not waste excessive amounts of bandwidth and hard drive |
| 49 |
+space. Also, you should not add binary (non-ASCII) files to the |
| 50 |
+Portage CVS tree. If you need to do this in another CVS tree, for |
| 51 |
+example, if you need to add a small PNG graphic for whatever reason, |
| 52 |
+be sure to add it to CVS by using the <c>-kb</c> option, like so: |
| 53 |
+</p> |
| 54 |
+ |
| 55 |
+<pre caption="Adding binary files to CVS"> |
| 56 |
+# <i>cvs add -kb myphoto.png</i> |
| 57 |
+</pre> |
| 58 |
+ |
| 59 |
+<p> |
| 60 |
+The <c>-kb</c> option tells CVS that <path>myphoto.png</path> is a binary |
| 61 |
+file and should be treated specially. For example, merging the |
| 62 |
+differences between two different versions of this file should not be |
| 63 |
+allowed to happen, for obvious reasons. Also, speaking of merging |
| 64 |
+changes, any patches you add to Portage should generally <e>not</e> be |
| 65 |
+compressed. This will allow CVS to merge changes and correctly inform |
| 66 |
+developers of conflicts. |
| 67 |
+</p> |
| 68 |
+ |
| 69 |
+<p> |
| 70 |
+Remember, the packages that you commit must be <e>ready</e> <e>out of the |
| 71 |
+box</e> for end users when committed as stable. Make sure that you have a good |
| 72 |
+set of default settings that will satisfy the majority of systems and |
| 73 |
+users that will use your package. If your package is broken, and you are |
| 74 |
+not sure how to get it to work, check some other distributions that have |
| 75 |
+done their own versions of the package. You can check |
| 76 |
+<uri link="http://cvs.mandriva.com/cgi-bin/viewvc.cgi/SPECS/">Mandriva</uri> |
| 77 |
+or <uri link="http://www.debian.org/distrib/packages">Debian</uri> or |
| 78 |
+<uri link="http://cvs.fedora.redhat.com/">Fedora</uri> for some |
| 79 |
+examples. |
| 80 |
+</p> |
| 81 |
+ |
| 82 |
+<p> |
| 83 |
+When committing to CVS, all developers should use <c>repoman commit</c> |
| 84 |
+instead of <c>cvs commit</c> to submit their ebuilds. Before committing, |
| 85 |
+please run <c>repoman full</c> to make sure you didn't forget something. |
| 86 |
+</p> |
| 87 |
+ |
| 88 |
+</body> |
| 89 |
+</subsection> |
| 90 |
+ |
| 91 |
+<subsection> |
| 92 |
+<title>Initial Architecture Keywords</title> |
| 93 |
+<body> |
| 94 |
<p> |
| 95 |
When adding a new ebuild, you should only include <c>KEYWORDS</c> for |
| 96 |
architectures on which you have actually tested the ebuild, confirming |
| 97 |
@@ -33,6 +105,73 @@ work on those architectures. |
| 98 |
</p> |
| 99 |
|
| 100 |
</body> |
| 101 |
+</subsection> |
| 102 |
+ |
| 103 |
+<subsection> |
| 104 |
+<title>CVS Commit Policy</title> |
| 105 |
+<body> |
| 106 |
+ |
| 107 |
+<ul> |
| 108 |
+<li>Always run <c>repoman scan</c> before you commit.</li> |
| 109 |
+<li>Please run <c>repoman full</c> before you commit.</li> |
| 110 |
+<li>Always test that <path>package.mask</path> is okay by doing |
| 111 |
+<c>emerge --pretend mypkg</c> before you commit and check |
| 112 |
+that it doesn't contain any conflicts.</li> |
| 113 |
+<li>Always update the <path>ChangeLog</path> before you commit.</li> |
| 114 |
+<li>Always commit the updated <path>package.mask</path> before |
| 115 |
+the updated package, in case conflicts occur while you commit |
| 116 |
+<path>package.mask</path>.</li> |
| 117 |
+<li>Always do atomic commits; if you commit a package with a new license, |
| 118 |
+or that is masked, then first commit the revised <path>package.mask</path> and/or license, |
| 119 |
+then commit the ebuild, <path>ChangeLog</path>, patches |
| 120 |
+and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go |
| 121 |
+to avoid breaking users' installations.</li> |
| 122 |
+</ul> |
| 123 |
+ |
| 124 |
+</body> |
| 125 |
+</subsection> |
| 126 |
+ |
| 127 |
+<subsection> |
| 128 |
+<title>The files Directory</title> |
| 129 |
+<body> |
| 130 |
+ |
| 131 |
+<p> |
| 132 |
+As noted earlier, under each package subdirectory is |
| 133 |
+a <path>files/</path> directory. Any patches, configuration files, or |
| 134 |
+other ancillary files your package might require should be added to |
| 135 |
+this directory; any files bigger than 20KB-or-so should go to the |
| 136 |
+mirrors to lower the amount of (unneeded) files our users have to |
| 137 |
+download. You may want to consider naming patches you create yourself |
| 138 |
+just to get your package to build with a version-specific name, such |
| 139 |
+as <path>mypkg-1.0-gentoo.diff</path>, or more |
| 140 |
+simply, <path>1.0-gentoo.diff</path>. Also note that the |
| 141 |
+<path>gentoo</path> extension informs people that this patch was created |
| 142 |
+by us, the Gentoo Linux developers, rather than having been grabbed from a |
| 143 |
+mailing list or somewhere else. Again, you should not compress these |
| 144 |
+patches because CVS does not play well with binary files. |
| 145 |
+</p> |
| 146 |
+ |
| 147 |
+<p> |
| 148 |
+Consider prefixing or suffixing (such as <path>mypkg-1.0</path>) every file |
| 149 |
+you put into the <path>files/</path> directory, so that the files used for |
| 150 |
+each individual version on an ebuild are distinguishable from one another, and |
| 151 |
+so that the changes between different revisions are visible. This is generally |
| 152 |
+a really good idea :). You may want to use a different suffix if you wish to |
| 153 |
+convey more meaning with the patch name. |
| 154 |
+</p> |
| 155 |
+ |
| 156 |
+<p> |
| 157 |
+If you have many files that should go into the <path>files/</path> directory, |
| 158 |
+consider creating subdirectories such as <path>files/1.0/</path> and putting the |
| 159 |
+relevant files in the appropriate subdirectory. If you use this method, |
| 160 |
+you do not need to add version information to the names of the files, |
| 161 |
+which is often more convenient. |
| 162 |
+</p> |
| 163 |
+ |
| 164 |
+</body> |
| 165 |
+</subsection> |
| 166 |
+ |
| 167 |
+</body> |
| 168 |
</section> |
| 169 |
|
| 170 |
<section> |
Archives