Improve and correct stack upload documentation

Author: mpilgrem

doc/GUIDE_advanced.md

@@ -250,16 +250,36 @@ ghc-9.0.2
 Hackage only accepts packages for uploading in a standard form, a compressed
 archive ('tarball') in the format produced by Cabal's `sdist` action.
 
-`stack sdist` generates an file for your package, in the format accepted by
+`stack sdist` generates a file for your package, in the format accepted by
 Hackage for uploads. The command will report the location of the generated file.
-The location can be changed from the default using the
-`--tar-dir <path_to_directory>` option.
 
-By default, the command will check the package for common mistakes. This can be
-disabled with the flag `--ignore-check`.
+### The `stack sdist --ignore-check` flag
 
-Setting the flag `--test-tarball` will cause Stack to attempt to build the
-resulting package archive, to test it.
+Pass the flag to disable checks of the package for common mistakes. By default,
+the command will check the package for common mistakes.
+
+### The `stack sdist --pvp-bounds` option
+
+The `--pvp-bounds <pvp_bounds_mode>` option determines whether and, if so, how
+PVP version bounds should be added to the Cabal file of the package. The
+available modes for basic use are: `none`, `lower`, `upper`, and `both`. The
+available modes for use with Cabal file revisions are `lower-revision`,
+`upper-revision` and `both-revision`.
+
+For futher information, see the
+[YAML configuration](yaml_configuration.md#pvp-bounds) documentation.
+
+### The `stack sdist --tar-dir` option
+
+The `--tar-dir <path_to_directory>` option determines whether the package
+archive should be copied to the specified directory.
+
+### The `stack sdist --[no-]test-tarball` flag
+
+Default: Disabled
+
+Set the flag to cause Stack to test the resulting package archive, by attempting
+to build it.
 
 ## The `stack templates` command
 
@@ -350,43 +370,99 @@ accepts an optional `--to` argument to specify the destination directory.
 
 ## The `stack upload` command
 
-`stack upload` uploads an sdist to Hackage. As of version
-[1.1.0](https://docs.haskellstack.org/en/v1.1.0/ChangeLog/) Stack will also
-attempt to GPG sign your packages as per
-[our blog post](https://www.fpcomplete.com/blog/2016/05/stack-security-gnupg-keys).
+Hackage accepts packages for uploading in a standard form, a compressed archive
+('tarball') in the format produced by Cabal's `sdist` action.
+
+`stack upload` generates a file for your package, in the format accepted by
+Hackage for uploads, and uploads the package to Hackage. For example, if the
+current working directory is the root directory of your project:
+
+~~~text
+stack upload .
+~~~
+
+### The `HACKAGE_USERNAME` and `HACKAGE_PASSWORD` environment variables
+
+[:octicons-tag-24: 2.3.1](https://github.com/commercialhaskell/stack/releases/tag/v2.3.1)
+
+`stack upload` will request a Hackage username and password to authenticate.
+This can be avoided by setting the `HACKAGE_USERNAME` and `HACKAGE_PASSWORD`
+environment variables. For
+example:
+
+=== "Unix-like"
 
-* `--no-signature` disables signing of packages
-* `--candidate` upload a
-  [package candidate](http://hackage.haskell.org/upload#candidates)
-* Hackage API key can be used instead of username and password. For example, on
-  Unix-like operating systems command:
+    ~~~text
+    export $HACKAGE_USERNAME="<username>"
+    export $HACKAGE_PASSWORD="<password>"
+    stack upload .
+    ~~~
 
-  ~~~text
-  HACKAGE_KEY=<api_key>
-  stack upload .
-  ~~~
+=== "Windows (with PowerShell)"
 
-  and on Windows (with PowerShell) command:
+    ~~~text
+    $Env:HACKAGE_USERNAME='<username>'
+    $Env:HACKAGE_PASSWORD='<password>'
+    stack upload .
+    ~~~
 
-  ~~~text
-  $Env:HACKAGE_KEY=<api_key>
-  stack upload .
-  ~~~
+### The `HACKAGE_KEY` environment variable
 
-* `username` and `password` can be read by setting the following environment
-  variables. On Unix-like operating systems command:
+[:octicons-tag-24: 2.7.5](https://github.com/commercialhaskell/stack/releases/tag/v2.7.5)
 
-  ~~~text
-  export $HACKAGE_USERNAME="<username>"
-  export $HACKAGE_PASSWORD="<password>"
-  ~~~
+Hackage allows its members to register an API authentification token and to
+authenticate using the token.
 
-  and on Windows (with PowerShell) command:
+A Hackage API authentification token can be used with `stack upload` instead of
+username and password, by setting the `HACKAGE_KEY` environment variable. For
+example:
+
+=== "Unix-like"
+
+     ~~~text
+     HACKAGE_KEY=<api_authentification_token>
+     stack upload .
+     ~~~
+
+=== "Windows (with PowerShell)"
+
+     ~~~text
+     $Env:HACKAGE_KEY=<api_authentification_token>
+     stack upload .
+     ~~~
+
+### The `stack upload --candidate` flag
+
+Pass the flag to upload a
+[package candidate](http://hackage.haskell.org/upload#candidates).
+
+### The `stack upload --ignore-check` flag
+
+Pass the flag to disable checks of the package for common mistakes. By default,
+the command will check the package for common mistakes.
+
+### The `stack upload --pvp-bounds` option
+
+The `--pvp-bounds <pvp_bounds_mode>` option determines whether and, if so, how
+PVP version bounds should be added to the Cabal file of the package. The
+available modes for basic use are: `none`, `lower`, `upper`, and `both`. The
+available modes for use with Cabal file revisions are `lower-revision`,
+`upper-revision` and `both-revision`.
+
+For futher information, see the
+[YAML configuration](yaml_configuration.md#pvp-bounds) documentation.
+
+### The `stack upload --tar-dir` option
+
+The `--tar-dir <path_to_directory>` option determines whether the package
+archive should be copied to the specified directory.
+
+### The `stack upload --[no-]test-tarball` flag
+
+Default: Disabled
 
-  ~~~text
-  $Env:HACKAGE_USERNAME='<username>'
-  $Env:HACKAGE_PASSWORD='<password>'
-  ~~~
+Set the flag to cause Stack to test the resulting package archive, by attempting
+to build it.
 
 ## Docker integration
 

doc/yaml_configuration.md

@@ -975,6 +975,11 @@ default. For more information on this change, see
 
 [:octicons-tag-24: 0.1.5.0](https://github.com/commercialhaskell/stack/releases/tag/v0.1.5.0)
 
+Default: `none`
+
+Command line equivalent (takes precedence): `stack sdist --pvp-bounds` option or
+`stack upload --pvp-bounds` option
+
 !!! warning
 
     As of Stack 1.6.0, this feature does not reliably work, due to issues with
@@ -985,7 +990,11 @@ default. For more information on this change, see
 
 When using the `sdist` and `upload` commands, this setting determines whether
 the Cabal file's dependencies should be modified to reflect PVP lower and upper
-bounds. Values are `none` (unchanged), `upper` (add upper bounds), `lower` (add
+bounds.
+
+#### Basic use
+
+Values are `none` (unchanged), `upper` (add upper bounds), `lower` (add
 lower bounds), and both (and upper and lower bounds). The algorithm it follows
 is:
 
@@ -1002,16 +1011,19 @@ pvp-bounds: none
 For further information, see the announcement
 [blog post](https://www.fpcomplete.com/blog/2015/09/stack-pvp).
 
-!!! note
+#### Use with Cabal file revisions
+
+[:octicons-tag-24: 1.5.0](https://github.com/commercialhaskell/stack/releases/tag/v1.5.0)
+
+Each of the values listed above supports adding `-revision` to the end of the
+value, e.g. `pvp-bounds: both-revision`. This means that, when uploading to
+Hackage, Stack will first upload your tarball with an unmodified Cabal file, and
+then upload a Cabal file revision with the PVP bounds added.
 
-    Since Stack 1.5.0, each of the values listed above supports adding
-    `-revision` to the end of each value, e.g. `pvp-bounds: both-revision`. This
-    means that, when uploading to Hackage, Stack will first upload your tarball
-    with an unmodified Cabal file, and then upload a Cabal file revision with
-    the PVP bounds added. This can be useful - especially combined with the
-    [Stackage no-revisions feature](http://www.snoyman.com/blog/2017/04/stackages-no-revisions-field) -
-    as a method to ensure PVP compliance without having to proactively fix
-    bounds issues for Stackage maintenance.
+This can be useful - especially combined with the
+[Stackage no-revisions feature](http://www.snoyman.com/blog/2017/04/stackages-no-revisions-field) -
+as a method to ensure PVP compliance without having to proactively fix bounds
+issues for Stackage maintenance.
 
 ### recommend-stack-upgrade