Merge pull request #13 from creffett/master

Clarify difference between _p and -r in ebuild names

1 files changed, 12 insertions, 1 deletions

diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml
index 52216d1..de2380a 100644
--- a/ebuild-writing/file-format/text.xml
+++ b/ebuild-writing/file-format/text.xml
@@ -70,7 +70,7 @@ what portage considers to be the 'lowest' version comes first.
   </tr>
   <tr>
     <ti>_p</ti>
-    <ti>Patch level</ti>
+    <ti>Patch release</ti>
   </tr>
 </table>
 
@@ -98,12 +98,23 @@ No integer part of the version may be longer than 18 digits.
 Finally, version may have a Gentoo revision number in the form <c>-r1</c>. The initial
 Gentoo version should have no revision suffix, the first revision should be
 <c>-r1</c>, the second <c>-r2</c> and so on. See <uri link="::general-concepts/ebuild-revisions"/>.
+Revision numbers are distinguished from patch releases by revision bumps being
+changes by Gentoo developers, while patch releases are new releases by upstream (with the exception
+of snapshots, see below).
 </p>
 
 <p>
 Overall, this gives us a filename like <c>libfoo-1.2.5b_pre5-r2.ebuild</c>.
 </p>
 
+<p>
+When packaging a snapshot of a source repository, there are two commonly used formats. The first
+treats the snapshot as a patch to the previous version, and so the ebuild version is in the format
+$(last-released-version)_pYYYYMMDD. Alternatively, the snapshot may be treated as a pre-release to
+an upcoming version, usually used when a release is anticipated but not out yet. The format for this
+is $(upcoming-version)_preYYYYMMDD.
+</p>
+
 </body>
 </section>