Using another package set : documentation and/or issues

[oliver3]

I wanted to try psc-package for a new project based on the node-telegram-bot-api from @justinwoo, but ran into several issues which I still don't understand. Maybe they are bugs, maybe just documentation issues, but here is a transcript of what I tried to do. Sorry for the lengthy issue, but I just don't know what I did wrong, so I hope people will take the time to skim through it and give me some insights and distill the improvements on psc-package

---

$ psc-package init
$ psc-package install node-telegram-bot-api
Package node-telegram-bot-api does not exist in package set

Right, I knew that, but I already saw that there is another package set from Justin that does contain it!
Editing psc-package.json to have source "https://github.com/justinwoo/package-sets.git", then:

$ psc-package install node-telegram-bot-api
Package node-telegram-bot-api does not exist in package set

Oh, ok.. maybe it needs some sort of update.. What is the difference between update and updates?

$ psc-package update
Updating 1 packages...
Update complete

$ psc-package install node-telegram-bot-api
Package node-telegram-bot-api does not exist in package set

$ psc-package updates
Checking 187 packages for updates.
..........

$ psc-package install node-telegram-bot-api
Package node-telegram-bot-api does not exist in package set

$ psc-package init
psc-package.json already exists

$ rm -rf .psc-package/
$ psc-package update
warning: Could not find remote branch psc-0.11.7 to clone.
fatal: Remote branch psc-0.11.7 not found in upstream origin

This I really do not understand. Is it a problem with the package set? But there is no mention of the psc in the package set... Maybe a bug?

Let me try to init a project with the new package-set from the start. I remember reading some flag to do this..... But cannot find in the README or in the --help how to do that :(

Eventually found that it is in the message that psc-package init gives. This could be mentioned in the help or readme as well?

$ rm psc-package.json
$ psc-package init --set https://github.com/justinwoo/package-sets.git
Initializing new project in current directory
warning: Could not find remote branch https://github.com/justinwoo/package-sets.git to clone.
fatal: Remote branch https://github.com/justinwoo/package-sets.git not found in upstream origin

Wat? Maybe wrong format?

$ psc-package init --set https://github.com/justinwoo/package-sets
psc-package.json already exists
$ rm psc-package.json
$ psc-package init --set https://github.com/justinwoo/package-sets
Initializing new project in current directory
warning: Could not find remote branch https://github.com/justinwoo/package-sets to clone.
fatal: Remote branch https://github.com/justinwoo/package-sets not found in upstream origin

Ok... I don't know what to try anymore, giving up :(

(One day later)

Initializing new project in current directory
Using the default package set for PureScript compiler version 0.11.7
(Use --source / --set to override this behavior)

Oh.. I see now that --source and --set are not just aliases, as I assumed..

$ psc-package init --source https://github.com/justinwoo/package-sets.git
Missing: --set ARG

Usage: psc-package init [--set ARG] [--source ARG]
  Create a new psc-package.json file

Why not just the default set, as psc-package init does?

$ psc-package init --source https://github.com/justinwoo/package-sets.git --set 0.11.7
Initializing new project in current directory
warning: Could not find remote branch 0.11.7 to clone.
fatal: Remote branch 0.11.7 not found in upstream origin

Ah, so the set is some branch on the package-set? Does not seem to be that way? How to figure out what a valid set is?

Now really giving up :(

[justinwoo]

I wrote about upgrading from Bower to Psc-Package in a post here: https://qiita.com/kimagure/items/0d9354900d7a7dbd3864#step-2-init-psc-package

In the post I manually edit the psc-package file and the "set" is my branch/tag name and "source" is the package set repo.

We do need to try to improve the docs though I think, but I personally don't know much other than just editing the psc-package file.

[nwolverson]

I think the fact that .psc-package is keyed on only the set and not in any way the source may lead to a bunch of the confusing errors, if that was resolved some of the above commands could be more helpful. I think any edit to psc-package.json should lead to a consistent state after psc-package update, while just now if you change to a different source with the same package set tag I don't know what would happen.

The rest of the above seems to stem from a basic misunderstanding of the package set model, e.g. that it's 1:1 with git repositories (I think https://github.com/purescript/psc-package#the-psc-packagejson-format is fairly clear but maybe comes too late).

On the update / updates confusion - I think the psc-package cli help text is not terrible but slightly unclear - I think there's rather a split between package-consumption related commands and package-set-maintenance commands, which could be clearer