Publishing a library with Spago

[JordanMartinez]

Coming from @f-f's comment here (very end of the comment):

You can use spago to develop libraries, the only part that require you to use pulp and bower are versioning and publishing on bower. The reasons why this is required are stated here.
In general you'll have a bower file, but it's only necessary that it contains the right list of dependencies, the version can be * (at least for adding it to the package set).
Basically all of this can be automated, and this would mean having spago version and spago publish

Followed by my comment here (very end of comment):

Perhaps I should clarify that statement. The point is that you can't publish docs to Pursuit unless you are using bower at some point. While it may be possible to use spago to create libraries, I'm not sure whether that would be a good idea because I could "patch" a dependency in my package set before doing that and potentially break expectations.
So, perhaps that could work but only if the package set did not include any overrides or additions?

[f-f]

The topic of "how do I publish with spago" is coming up quite often recently, so I though I'd recap the current situation:

• The context is that the PureScript ecosystem uses the Bower registry as a "unique names registry". So in order to "publish" a package one needs to add it there, and eventually to package-sets.
  Consequentially, package-sets requires (full instructions here) that packages in it:

  • are in the Bower registry
  • use pulp version (because this gives versions with vX.Y.Z)
  • use pulp publish (because AFAIK there's no specification on how to publish a package other than "what the compiler and pulp do")

• So for the time being one can develop normally with spago, and then when they want to publish they have to:

  • make a bowerfile that includes the spago dependencies
  • run pulp version
  • run pulp publish

  A package published in this way is e.g. purescript-rave (/cc @reactormonk: is all of this accurate?)

---

To address your concern about people "patching dependencies": the fact that the above workflow is required (in particular bower i -p has to succeed in order for the package being good for the package set) means that people can only depend on published packages.

I.e. for what concerns "publishing" it doesn't matter if a package compiles with spago or psc-package, it has to compile with bower. So everything is fine on this side :)

---

The plan

There are a few desiderable things that we could do (in this order):

• document the current workflow in a section of the README

• add spago new-version command to upgrade the version in your spago.dhall (we don't have this config key yet) - akin to pulp version.
  An alternative design is that we could skip having an explicit version field, and just rely on what git tells us. I.e. we search for vX.Y.Z tags, and we add and push a new one

  EDIT: this is now tracked in Add spago bump-version #203

• add spago publish to publish to both the bower registry and package-sets. It would:

  • generate an ephemeral bower.json in the .spago directory (the idea is that this generation is deterministic starting from the spago.dhall, so you don't actually need to version the bower.json file). The versions of packages listed there can come from the package set or can even be * (I think there are drawback to either choice)
    However, it might be that bower actually requires the bower.json to be checked in
  • call git and bower commands in the background to publish a git tag and publish on the bower registry (this would require bower to be in the path)
  • print out a link to open an issue in package-sets about adding the package there (basically spago upstream command #72)

  EDIT: this is now tracked in Add spago publish #204

[reactormonk]

Can confirm, is accurate.

[JordanMartinez]

To address your concern about people "patching dependencies": the fact that the above workflow is required (in particular bower i -p has to succeed in order for the package being good for the package set) means that people can only depend on published packages.

I.e. for what concerns "publishing" it doesn't matter if a package compiles with spago or psc-package, it has to compile with bower. So everything is fine on this side :)

Gotcha. That addresses the concern I raised then.

I know I read somewhere that packages are required to be published to the Bower registry before they can be added into the package set to avoid Haskell's problem of splitting the ecosystem. However, I don't see an explanation of that written anywhere in this project. (Maybe it was stated in the Slack chatroom?)
I also realize that you've explained these things multiple times elsewhere, so perhaps this just needs a centralized place that links to all of those?

[f-f]

@JordanMartinez

I know I read somewhere that packages are required to be published to the Bower registry before they can be added into the package set to avoid Haskell's problem of splitting the ecosystem. However, I don't see an explanation of that written anywhere in this project. (Maybe it was stated in the Slack chatroom?)
I also realize that you've explained these things multiple times elsewhere, so perhaps this just needs a centralized place that links to all of those?

Yeah this is documented in the package-sets contributing guidelines I linked above, and the explanation was purposefully left out from Spago's docs so far, as I didn't have a clear plan forward and didn't want to confuse readers.
I think at this point the plan is quite clear - TL;DR: use pulp for now, and then implement version and publish here in Spago before 1.0 - as detailed in my above comment

[JordanMartinez]

the explanation was purposefully left out from Spago's docs so far, as I didn't have a clear plan forward and didn't want to confuse readers.

Makes sense.

Yeah this is documented in the package-sets contributing guidelines I linked above

I'm going to be nit-picky here: the words used there are "should" not "required"/"must".
Also, I recall reading that section earlier and it wasn't immediately clear to me that publishing to bower was necessary, partly because pulp version is mentioned first to address a seemingly unimportant issue and then bower is later mentioned. Once one understands the full context, the reference to pulp version makes sense: "Oh, I need to do that because I need to publish first to bower and using semver is best handled by pulp."

Until the plan gets implemented, would you mind if I submit a PR that clarifies that contributing guideline a bit more?

[f-f]

Until the plan gets implemented, would you mind if I submit a PR that clarifies that contributing guideline a bit more?

Sure, I think having clear contribution guidelines in package-sets is faily independent from any implementation plan here 🙂

[JordanMartinez]

Ok. I'll make this a goal for the upcoming week

[f-f]

I opened #203 and #204 to keep track of the implementation work for this, so this is safe to close 😊