Documentation checksums.ini

src/doc/en/developer/packaging.rst

@@ -379,11 +379,32 @@ account.
 Checksums
 ---------
 
-The ``checksums.ini`` file contains checksums of the upstream tarball.
-It is autogenerated, so you just have to place the upstream tarball in
-the ``SAGE_ROOT/upstream/`` directory and run::
+The ``checksums.ini`` file contains the filename pattern of the
+upstream tarball (without the actual version) and its checksums. So if
+upstream is ``$SAGE_ROOT/upstream/FoO-1.3.tar.gz``, create a new file
+``$SAGE_ROOT/build/pkgs/foo/checksums.ini`` containing only::
 
-    [user@localhost]$ sage --fix-pkg-checksums
+    tarball=FoO-VERSION.tar.gz
+
+Sage internally replaces the ``VERSION`` substring with the content of
+``package-version.txt``. To recompute the checksums, run::
+
+    [user@localhost]$ sage --package fix-checksum foo
+
+which will modify the ``checksums.ini`` file with the correct
+checksums.
+
+
+Utility script to create package
+================================
+
+Assuming that you have downloaded
+``$SAGE_ROOT/upstream/FoO-1.3.tar.gz``, you can use::
+
+    [user@localhost]$ sage --package create foo --version 1.3 --tarball FoO-VERSION.tar.gz --type experimental
+
+to create ``$SAGE_ROOT/build/pkgs/foo/package-version.txt``,
+``checksums.ini``, and ``type`` in one step.
 
 
 .. _section-manual-build: