Update publish instructions (#465)

* Add explanation on bower situation

* Bump list number; add note about verify check

* Fix indentation

* Update static/help-docs/authors.md

Co-authored-by: Thomas Honeyman <[email protected]>

* Update changelog

Co-authored-by: Thomas Honeyman <[email protected]>

Author: JordanMartinez

CHANGELOG.md

@@ -8,6 +8,7 @@ the most up-to-date version of this file.
 ## v0.9.0
 
 - Update `purescript` to `0.15.0` (@JordanMartinez)
+- Fix publishing instructions (@JordanMartinez)
 
 ## v0.8.7
 

static/help-docs/authors.md

@@ -1,16 +1,55 @@
 ## <a name="submitting-packages"></a>How to submit packages
 
+Packages can only be uploaded to Pursuit if the following conditions are true:
+- The repository is not a mono-repo.
+- Your project must be registred in the [`purescript/registry` repo's `new-packages.json` file](https://github.com/purescript/registry/blob/master/new-packages.json). If it's not yet there, then submit a PR adding it.
+- `bower install` exits successfully without any conflicts.
+- `pulp build` (and if applicable `pulp test`) exits successfully without any conflicts.
+- A tag points to the same commit that is currently checked out (whether by a checked out commit, branch, or tag)
+- The `git` working directory is clean.
+
+`bower` often causes problems in publishing, and this is something that will be fixed once the PureScript Registry is started. Until then, keep the following in mind:
+- In your package's root directory, always start from a clean bower state by running `rm -rf bower_components/ && bower cache clean`
+- If a dependency is **not** in the Bower registry (e.g. `bower info purescript-package-name` returns `ENOTFOUND`), it can be installed using the long form. For example:
+    - Schema: `bower install --save <package-name>=<git-https-endpoint>#<version-range>`
+    - Example: `bower install --save purescript-js-uri=https://github.com/purescript-contrib/purescript-js-uri.git#^1.0.0`
+- If you run `bower install` and the command encounters a version conflict and asks which one to use for a given dependency, then your package cannot be published to Pursuit. There are two possible reasons for this:
+    - one or more of your `bower.json` file's `dependencies` or `devDependencies` (if used) needs to be updated
+        - Try running the following:
+
+          ```
+          # installs `ncu` globally
+          npm i -g npm-check-updates
+          # get list of outdated packages
+          ncu -p bower
+          # update versions to latest ones automatically
+          ncu -u -bower
+          ```
+
+    - one or more of your dependencies (e.g. `bar`) did not update their `bower.json` file's `dependencies` field to refer to the new version of their dependency (e.g. `baz`) before publishing it (e.g. `bar`). As a result, your direct dependency, `[email protected]`, may depend on `[email protected]` while your other direct dependency `[email protected]` still depends on `[email protected]`. Bower will complain when it isn't sure whether to use `[email protected]` or `[email protected]`.
+        - Try contacting the author of the package and ask them to update their `bower.json` file correctly and publish a new release.
+
 1. Put the code up on GitHub. (Currently, GitHub is the only supported hosting method. If you'd rather host your code somewhere else, please open an issue and let us know).
 
-2. (Optional, highly recommended) Check that the documentation looks sensible locally before publishing by running `pulp docs -- --format html`.
+2. Verify that `bower install`, `pulp build`, and (if applicable) `pulp test` exit successfully.
+
+3. (Optional, highly recommended) Check that the documentation looks sensible locally before publishing by running `pulp docs -- --format html`.
+
+4. Create a git tag for the version you're releasing, if you haven't already. It is recommended to use `pulp version` to do this for you, as doing it this way will also check your package for common errors.
+
+5. Authenticate to GitHub by running `pulp login`. (This is necessary in order for us to be able to tell who uploaded which packages).
 
-3. Create a git tag for the version you're releasing, if you haven't already. It is recommended to use `pulp version` to do this for you, as doing it this way will also check your package for common errors.
+6. Change to your project directory and run `pulp publish`. This will the push commits and the relevant tag to your "origin" Git remote, and then generate your documentation and upload it to Pursuit.
 
-4. Authenticate to GitHub by running `pulp login`. (This is necessary in order for us to be able to tell who uploaded which packages).
+    `pulp publish` also accepts a `--no-push` flag which skips the Bower registration check as well as pushing commits (this is useful for uploading other people's packages, if you ever need to do this). There is also a `--push-to` option which allows you to specify a different Git remote to push tags and commits to.
 
-5. Change to your project directory and run `pulp publish`. This will register your package on Bower if necessary, push commits and the relevant tag to your "origin" Git remote, and then generate your documentation and upload it to Pursuit.
+    **Note: If `pulp publish` fails with a `400` error, try running it a second time.** Usually, your project's documentation will be successfully published on the second run. For example:
 
-   `pulp publish` also accepts a `--no-push` flag which skips the Bower registration check as well as pushing commits (this is useful for uploading other people's packages, if you ever need to do this). There is also a `--push-to` option which allows you to specify a different Git remote to push tags and commits to.
+    ```
+    # tag gets pushed in first run, so we don't need it in the second run
+    yes | pulp publish
+    yes | pulp publish --no-push
+    ```
 
 
 Your package, together with documentation, should now appear in Pursuit.