[lintian] 02/03: Improve the long description of epoch-change-without-comment. Based on suggestions by Raphael Hertzog and Ian Jackson - thanks! (Closes: #889814)

[Chris Lamb <chris@chris-lamb.co.uk>]

This is an automated email from the git hooks/post-receive script.

lamby pushed a commit to branch master
in repository lintian.

commit 2a7f83e0fb26b06d2e4f5ea0f4fb97390eafb2d7
Author: Chris Lamb <lamby@debian.org>
Date:   Wed Feb 7 20:10:30 2018 +0000

    Improve the long description of epoch-change-without-comment. Based on suggestions by Raphael Hertzog and Ian Jackson - thanks! (Closes: #889814)
---
 checks/changelog-file.desc | 15 ++++++++++++++-
 debian/changelog           |  4 ++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/checks/changelog-file.desc b/checks/changelog-file.desc
index b67966a..6fd4f92 100644
--- a/checks/changelog-file.desc
+++ b/checks/changelog-file.desc
@@ -428,7 +428,20 @@ Info: The previous version of this package had a different version epoch
  (eg. 2:1.0-1) to the current version and there's no reference to this in
  the changelog entry.
  .
- This may indicate a mistake in setting the version.
+ Epochs exist to cope with changes to the upstream version numbering
+ scheme. Whilst they are a powerful tool, increasing or adding an epoch
+ has many downsides, including being misleading to users and being
+ aesthetically unappealing. Whilst they should be avoided, valid reasons
+ to add or increment the epoch include:
+ .
+  - Upstream changed their versioning scheme in a way that makes the
+    latest version lower than the previous one.
+  - You need to permanently revert to a lower upstream version. Temporary
+    revertions should use <tt>CURRENT+reallyFORMER</tt> until you can
+    upload the latest version again.
+ .
+ If you are unsure whether you need to increase the epoch for a package,
+ please consult the debian-devel mailing list.
  .
  Lintian looks in this version's changelog entry for the phrase "epoch".
 
diff --git a/debian/changelog b/debian/changelog
index 0182b69..33ac904 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -2,6 +2,10 @@ lintian (2.5.74) UNRELEASED; urgency=medium
 
   XXX: generate tag summary
 
+  * checks/changelog-file.desc:
+    + [CL] Improve the long description of epoch-change-without-comment.
+      Based on suggestions by Raphael Hertzog and Ian Jackson - thanks!
+      (Closes: #889814)
   * checks/cruft.desc:
     + [BR] Check for wasm files.  (Closes: #889102)
     + [CL] Factor out call to _ships_examples to avoid excessive looping

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/lintian/lintian.git