Merge Upload page improvements PR #553

Author: hvr

datafiles/templates/upload.html.st

@@ -39,15 +39,9 @@ the <code>Maintainer</code> field as above either to commit to supporting the fo
 yourself or to mark it as unsupported.
 </p>
 
-<p>Note that all of the above is a makeshift upload policy based on the features
-available in the newer hackage-server. The <code>Maintainer</code> field has its uses,
-as does maintainer user groups. The libraries mailing list should probably
-determine the best approach for this.
-</p>
-
 <h3>Upload forms</h3>
 <p>Some last formalities: to upload a package, you'll need a Hackage
-<a href="accounts.html">username</a> and password. (Alternatively, there's a
+<a href="accounts">username</a> and password. (Alternatively, there's a
 command-line interface via cabal-install, which also needs the same username
 and password.)
 </p>
@@ -72,36 +66,36 @@ See the notes at the bottom of the page.
   </li>
 
   <li>
-    Categories are determined by whatever you put in the <code>Category</code> field
-    (there's no agreed list of category names yet).
+    Categories are determined by whatever you put in the <code>Category</code> field.
+    You should try to pick existing categories when possible.
     You can have more than one category, separated by commas. If no other versions of
     the package exist, the categories automatically become the package's tags.
   </li>
 
   <li>
-    Documentation for library packages should be generated by a maintainer.
-    The means of doing this is still up in the air.
-  </li>
-
-  <li>
-    We have moved to Haddock 2, and expect some glitches.
-
-    If you notice anything broken, please report it on the
-    <a href="http://trac.haskell.org/haddock">Haddock bug tracker</a>.
-  </li>
-
-  <li>
-    In GHC 6.8, several modules were split from the <code>base</code> package
-    into other packages.
+    Occasional changes to the GHC base package can mean that some work needs to be done to make packages compatible across a range of versions.
+    See <a href="https://github.com/haskell-infra/hackage-trustees/blob/master/cookbook.md">these notes</a> for some tips in how to do so.
 
-    See <a href="http://www.haskell.org/haskellwiki/Upgrading_packages">these notes</a>
-    on making packages work with a range of versions of GHC.
+    There are some notes for upgrading <a href="http://www.haskell.org/haskellwiki/Upgrading_packages">much older</a> packages as well.
   </li>
 
   <li>
-    While <a href="http://www.haskell.org/haddock/">Haddock 2</a>
-    accepts GHC features, it is also more picky about comment syntax than
-    the old version.
+    The hackage-server attempts to build documentation for library
+    packages, but this can fail. Maintainers can generate their own
+    documentation and upload it by using something along the lines of the
+    shell script below (note that the last two commands are the key ones):
+
+    <pre>
+#!/bin/sh
+set -e
+
+dir=\$(mktemp -d dist-docs.XXXXXX)
+trap 'rm -r "\$dir"' EXIT
+
+cabal haddock --builddir="\$dir" --for-hackage --haddock-option=--hyperlinked-source
+# Starting with cabal 2.0, `--publish` is needed for uploading to non-candidate releases
+cabal upload -d \$dir/*-docs.tar.gz
+</pre>
   </li>
 
 </ul>