I was originally going to submit a PR to Spago with new instructions, but then I realized it would probably be best to have these instructions in a separate file so they can be linked to in multiple places.
Here’s my first nth draft. https://gist.github.com/ursi/2afa464536316c904b526b5f0674bba4
I’ll let the powers that be decide the best place to host the official document.
I have not yet followed this guide step by step to confirm that [at least one branch of] it works. If you are looking to publish a new package please do and let me know if I missed anything. Also please suggest improvements if you see any.
Edit: I have followed the instructions to completion and can confirm they work, at least in the case of having non-bower dependencies.
Thanks for writing this up! I think these instructions should live at https://pursuit.purescript.org/help/authors, but I would want to make some edits before merging that into Pursuit. Specifically:
Unique module names are highly recommended, but only a requirement if you want the package to be included in the package set, which isn’t actually necessary for most workflows (since you can always add it to your additions or overrides).
Searching Pursuit to check the module name isn’t already in use isn’t foolproof, because lots of packages haven’t made it up to Pursuit. I think the ideal way of doing it is via spago verify-set / the package-sets repo’s CI.
Checks which are already performed by purs publish (e.g. repo, license) don’t need to go in these instructions. I think it’s better to leave those to purs so that these instructions don’t go out of date.
Until Spago can handle packages which aren’t in the Bower registry during spago bump-version, I think we should recommend maintaining a bower.json file manually.
Come to think of it, using the package-sets repo’s CI to check for duplicate module names isn’t foolproof either, because not all packages are in the package set. But it will at least guarantee that your package can be added to the set without module name conflicts.
My reason for including it is two-fold. I think it’s a better UX to just not have any errors, and also iirc the errors you get just say something along the lines of you have missing field: license. It doesn’t tell you what the valid values of license are. Although that’s the errors by spago bump-version, I’ve never seen the pulp publish ones.
Are you saying it should recommend creating a bower.json from scratch instead of having spago get you most of the way there?
These errors are coming from purs itself, not pulp or spago, so they’ll be the same either way. We can say “and fix any problems it reports” so that at least they’re not unexpected.
The license error does say you have to use the “SPDX license expression format” which is correct, but it doesn’t help you discover what that is. I’d accept a compiler PR with a link eg if someone wanted to pick up https://github.com/purescript/purescript/pull/3834 where it was left off, that would be ideal.
Yes, for now I think it should recommend creating a bower.json from scratch. There’s not a lot you actually need: I think just name, repo, license, dependencies. You can also get the version ranges for all dependencies which are in the Bower registry just by running bower install purescript-foo purescript-bar [...] --save.
Actually come to think of it, I think the instructions for adding a package to the package set should (continue to) live in the package-sets repo, since that’s a more appropriate place for them and submitting to the package set is an optional extra and isn’t required for publishing a package. I think the instructions on Pursuit should just say “if you want to add your package to the official package set, please see the instructions on the purescript/package-sets repository” with a link.
Personally I’d much rather have a program do most of the work for me and not have to remember how to construct a proper bower.json and make sure I spell everything correctly. I would think that’s what most people would prefer . Would you mind expanding on why you think having spago do most of the work is the wrong recommendation?
I just think having to delete some dependencies from your spago.dhall temporarily, run that command, and re-add them again is very awkward, and it’s likely to be harder for people to understand why they are being asked to do these things and work out what to do if it does go wrong that way. Of course we can sidestep the issue entirely by having Spago draw the necessary information from the bower-packages.json and new-packages.json files from purescript/registry so that spago bump-version handles all cases by itself; in that case I think generating a bower.json file via spago bump-version would be the best option.
I can add more context to the situation - explain that spago currently will throw an error if it comes across a package not in the bower registry. And I guess I wouldn’t mind framing it as more of a hack than an official instruction, but I definitely want to leave it in there, as that is my preferred method and I’ve gotten positive feedback on it when helping others.
Well, personally, I think it’s a good way to go about doing things for now, so I am going to keep it on the instructions that are attached to my name. But absolutely feel free to change it in whatever way you see fit when adding the information to official places.
Actually, @hdgarrood, spago bump-version does produce its own error about missing license before it generates bower.json. I just verified on a small project and got this:
spago.exe: Error: Error while reading spago.dhall:
Explanation: a record is missing a required key.
The key missing is:
license
The keys in the record are:
dependencies, name, packages, sources
It doesn’t verify the validity of the fields though, so I can specify license = "foo", and it happily generates bower.json with it.
. Would you mind expanding on why you think having spago do most of the work is the wrong recommendation?