diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93f1c82..4726eb0 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/static/help-docs/authors.md b/static/help-docs/authors.md
index 1bfb41d..4f01e8c 100644
--- a/static/help-docs/authors.md
+++ b/static/help-docs/authors.md
@@ -1,16 +1,55 @@
## 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 =#`
+ - 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, `foo@2.0.0`, may depend on `baz@2.0.0` while your other direct dependency `bar@2.0.0` still depends on `baz@1.0.0`. Bower will complain when it isn't sure whether to use `baz@1.0.0` or `baz@2.0.0`.
+ - 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.