Skip to content

Instantly share code, notes, and snippets.

@ursi
Last active April 2, 2021 01:03
Show Gist options
  • Star 4 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save ursi/2afa464536316c904b526b5f0674bba4 to your computer and use it in GitHub Desktop.
Save ursi/2afa464536316c904b526b5f0674bba4 to your computer and use it in GitHub Desktop.
The current process for Publishing PureScript packages

PureScript is currently in a transitional period with regards to how new packages are published. As such, the process of publishing a package is rather arduous. You will need: spago, pulp, and bower.

  1. Make sure your package name is unique by searching for it in bower-packages.json and new-packages.json. Alternatively you can search Pursuit as well, but those two files are the sources of truth.
  2. Make sure the module names in your package are globally unique by searching for them on Pursuit. Unfortunately this is a requirement with the current technology. However, finding a module with the same name on Pursuit doesn't mean all hope is lost. Module names only have to be unique in the package set. So you can use the information in step 6 to see if your module name is actually taken. There is a good number of packages published on Pursuit that have not been added to the package set.
  3. Submit a PR adding your package to new-packages.json.
  4. If you only care about adding a package to the package set so it can be used with spago, and don't care to publish its documentation to pursuit. Skip to step 6.
  5. Publishing a package to Pursuit
    1. Add a license field to your spago.dhall containing a valid SPXD license.
    2. Add a repository field to your spago.dhall with the link to the Git repository.
    3. If you package only depends on packages already in the Bower registry (i.e. in bower-packages.json) go to step 5.v. If not, we have a bit of manual work to do.
    4. Your package depends on packages that aren't in the bower registry (Update: it seems that in newer version of spago this is fixed. Try going to step 5.v and come back here if that doesn't work.)
      1. Make sure your spago.dhall file is commited and create a new branch in your package repo.
      2. Remove the packages that aren't in the Bower registry from the dependencies in your spago.dhall and commit it.
      3. Use spago bump-version to generate a bower.json file that contains everything but the non-bower dependencies. Delete the tag if it was created.
      4. In the dependencies field of your newly generated bower.json, manually add back in your non-bower dependencies with the syntax "<repo name>": "<github username>/<repo name>#<version>".
      5. Switch to your master branch and commit the bower.json. You can delete the branch we used to generate it if you like.
      6. Run bower i install the dependencies with Bower.
      7. Use pulp version to create/bump your package version.
      8. Go to step 5.vi.
    5. Your package only depends on packages that are in the bower registry
      1. Use spago bump-version to generate a bower.json file and create/bump your package version.
    6. Use pulp publish to publish your documentation to Pursuit.
  6. Adding a package to the package set
    1. Fork and clone the package set repo.
    2. cd to src/groups, This is where you will add your package. Have a look around at the other package sets to see how to format things.
    3. Once you add your package, run make to update packages.json.
    4. Commit your changes and put in a PR.
    5. In order to use your package with the packages.dhall that spago generates for you, you need to ask for a new package to be released after your PR is accepted. You can do this in the PR itself or in a separate issue.
@tiye
Copy link

tiye commented Mar 20, 2021

I want to publish a package B, which depends on package A. And since Bower does not accept new package, A is not in bower. And then as I follow the steps, I got:

=>> spago bump-version -f v0.0.3
[info] Generating a new Bower config using the package set versions..
[error] Failed to run: `bower info --json purescript-cirru-parser#v0.0.2`
[error] [{
  "code": "ENOTFOUND",
  "data": {
    "endpoint": {
      "name": "",
      "source": "purescript-cirru-parser",
      "target": "v0.0.2"
    }
  },
  "id": "ENOTFOUND",
  "level": "error",
  "message": "Package purescript-cirru-parser not found",
...

is there any solution?

maybe caused by PR not merged in package-sets? purescript/package-sets#883

@ursi
Copy link
Author

ursi commented Mar 20, 2021

@jiyinyiyong it looks like you still have cirru-parser in your spago.dhall. Did you do step 5.iv.b?

@tiye
Copy link

tiye commented Mar 21, 2021

no, I forgot that step. but when I remove it, I can't build this project,

=>> spago test
[error] The following packages do not exist in your package set:
[error]   - cirru-parser

which means, I still need package-sets to merge my commit first?

@ursi
Copy link
Author

ursi commented Mar 21, 2021

You only remove it temporarily so that spago can generate most of the bower.json for you. I suggest taking a closer look at all the steps under 5.iv. Alternatively, you can create the entire bower.json by hand if you know how. You can find examples to copy by looking at the repo of any package on pursuit, and looking at step 5.iv.d to see how to add in your non-bower dependencies.

@tiye
Copy link

tiye commented Mar 21, 2021

dealing with multiple package managers makes the steps a lot more tricky for me. Thanks for the help, guess I need to take a break and wait for package-sets to merge the PR first and then look into this again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment