docs/manual: update details about hashes

This commit updates the manual about hashes, fixing a number of
issues:

 - Adding the .hash file should no longer be optional: it *must* be
   added. Therefore the wording "You can add ..." is changed to "When
   possible, you must add ...".

 - We are now checking hashes for Git downloaded packages, so fix this
   as well, and indicate more clearly which download methods have hash
   checking.

 - We no longer want to have auto-generated patches be downloaded
   through <pkg>_PATCH because such patches are not stable over time,
   and their hash can change. For example, downloading patches from
   github.com should no longer be done.

Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>

1 files changed, 16 insertions, 7 deletions

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index 08f5d42f91..00b2033904 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -439,8 +439,10 @@ rules].
 [[adding-packages-hash]]
 === The +.hash+ file
 
-Optionally, you can add a third file, named +libfoo.hash+, that contains
-the hashes of the downloaded files for the +libfoo+ package.
+When possible, you must add a third file, named +libfoo.hash+, that
+contains the hashes of the downloaded files for the +libfoo+
+package. The only reason for not adding a +.hash+ file is when hash
+checking is not possible due to how the package is downloaded.
 
 The hashes stored in that file are used to validate the integrity of the
 downloaded files.
@@ -515,10 +517,17 @@ the downloaded file is left in the download directory since this
 typically indicates that the +.hash+ file is wrong but the downloaded
 file is probably OK.
 
-Sources that are downloaded from a version control system (git, subversion,
-etc...) can not have a hash, because the version control system and tar
-may not create exactly the same file (dates, files ordering...), so the
-hash could be wrong even for a valid download. Therefore, the hash check
-is entirely skipped for such sources.
+Hashes are currently checked for files fetched from http/ftp servers,
+Git repositories, files copied using scp and local files. Hashes are
+not checked for other version control systems (such as Subversion,
+CVS, etc.) because Buildroot currently does not generate reproducible
+tarballs when source code is fetched from such version control
+systems.
+
+Hashes should only be added in +.hash+ files for files that are
+guaranteed to be stable. For example, patches auto-generated by Github
+are not guaranteed to be stable, and therefore their hashes can change
+over time. Such patches should not be downloaded, and instead be added
+locally to the package folder.
 
 If the +.hash+ file is missing, then no check is done at all.