|
1 | 1 | ## <a name="submitting-packages"></a>How to submit packages |
2 | 2 |
|
3 | | -Packages can only be uploaded to Pursuit if the following conditions are true: |
4 | | -- The repository is not a mono-repo. |
5 | | -- 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. |
6 | | -- `bower install` exits successfully without any conflicts. |
7 | | -- `pulp build` (and if applicable `pulp test`) exits successfully without any conflicts. |
8 | | -- A tag points to the same commit that is currently checked out (whether by a checked out commit, branch, or tag) |
9 | | -- The `git` working directory is clean. |
10 | | - |
11 | | -`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: |
12 | | -- In your package's root directory, always start from a clean bower state by running `rm -rf bower_components/ && bower cache clean` |
13 | | -- 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: |
14 | | - - Schema: `bower install --save <package-name>=<git-https-endpoint>#<version-range>` |
15 | | - - Example: `bower install --save purescript-js-uri=https://github.com/purescript-contrib/purescript-js-uri.git#^1.0.0` |
16 | | -- 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: |
17 | | - - one or more of your `bower.json` file's `dependencies` or `devDependencies` (if used) needs to be updated |
18 | | - - Try running the following: |
19 | | - |
20 | | - ``` |
21 | | - # installs `ncu` globally |
22 | | - npm i -g npm-check-updates |
23 | | - # get list of outdated packages |
24 | | - ncu -p bower |
25 | | - # update versions to latest ones automatically |
26 | | - ncu -u -p bower |
27 | | - ``` |
28 | | - |
29 | | - - 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]`. |
30 | | - - Try contacting the author of the package and ask them to update their `bower.json` file correctly and publish a new release. |
31 | | - |
32 | | -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). |
33 | | - |
34 | | -2. Verify that `bower install`, `pulp build`, and (if applicable) `pulp test` exit successfully. |
35 | | - |
36 | | -3. (Optional, highly recommended) Check that the documentation looks sensible locally before publishing by running `pulp docs -- --format html`. |
37 | | - |
38 | | -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. |
39 | | - |
40 | | -5. Authenticate to GitHub by running `pulp login`. (This is necessary in order for us to be able to tell who uploaded which packages). |
41 | | - |
42 | | -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. |
43 | | - |
44 | | - `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. |
45 | | - |
46 | | - **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: |
47 | | - |
48 | | - ``` |
49 | | - # tag gets pushed in first run, so we don't need it in the second run |
50 | | - yes | pulp publish |
51 | | - yes | pulp publish --no-push |
52 | | - ``` |
53 | | -
|
54 | | -
|
55 | | -Your package, together with documentation, should now appear in Pursuit. |
56 | | -
|
57 | | -## <a name="submit-automated"></a>Submitting packages from a script |
58 | | -
|
59 | | -You can also use Pulp to submit packages from a script. Pulp prompts for confirmation when you run `pulp publish`, so you will need to use a program like `yes` to answer affirmatively. |
60 | | -
|
61 | | -For example, if you want to automatically upload documentation from your Travis CI build on tags, you should add the following to your `after_script` build step: |
62 | | -
|
63 | | -`test -n "$TRAVIS_TAG" && ( yes | pulp publish --no-push )` |
64 | | -
|
65 | | -Alternatively, if you don't want to use Pulp for whatever reason, you can upload packages using Pursuit's HTTP API directly: |
66 | | -
|
67 | | -- Gzip the JSON output produced by `psc-publish` and save it to a file. |
68 | | -- If you don't already have one, get a GitHub API token by visiting <https://github.com/settings/tokens/new>. No scopes are required, since the token is only used for authentication. |
69 | | -- Make a POST request to https://pursuit.purescript.org/packages, with gzipped JSON as the request body, including a `Content-Encoding: gzip` header, and with your GitHub token in the Authorization header, like this: `Authorization: token {token}`. |
70 | | -
|
71 | | -For example, using curl: |
72 | | -
|
73 | | -``` |
74 | | -curl -X POST \ |
75 | | - https://pursuit.purescript.org/packages \ |
76 | | - --data-binary @pursuit.json.gz \ |
77 | | - -H 'Content-Encoding: gzip' \ |
78 | | - -H 'Accept: application/json' \ |
79 | | - -H "Authorization: token $(cat my-oauth-token.txt)" \ |
80 | | - -v |
81 | | -``` |
82 | | -
|
83 | | -If your submission is successful, Pursuit will return a 201 Created response, and the URL for your newly uploaded package will be in the Location header. |
| 3 | +Previously, users would need to use `bower` to upload packages' documentation. Uploading documentation is now handled by the PureScript Registry (still in alpha at the time of this writing). See the [PureScript Registry repo](https://github.com/purescript/registry) for how to register and publish packages and their documentation. For more context, read the Discourse announcement, [Registry Alpha Launched](https://discourse.purescript.org/t/registry-alpha-launched/3146). |
84 | 4 |
|
85 | 5 | ## <a name="package-deprecation"></a>How to mark package as deprecated |
86 | 6 |
|
|
0 commit comments