Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFE] More descriptive error when spago install isn't finding package #1287

Open
Hi-Angel opened this issue Sep 19, 2024 · 4 comments · May be fixed by #1290
Open

[RFE] More descriptive error when spago install isn't finding package #1287

Hi-Angel opened this issue Sep 19, 2024 · 4 comments · May be fixed by #1290

Comments

@Hi-Angel
Copy link

This came up as part of a discussion here.

Apparently, packages posted on Pursuit are getting combined into some sort of a "PSC set" which is then used by spago, and then an arbitrary package may or may not be present in such set. When it isn't, spago install prints:

[error] The following packages do not exist in your package set:
[error]   - purescript-halogen-menu, and nor does `halogen-menu`

The specifics that I mentioned above are impossible to infer from this message. A user has to know there exists some sort of versioning. A user can't even guess about such thing existing, because if you go to a Pursuit page of a package, you won't see no "PSC"s mentioned. As result, questions of that kind are getting reiterated by new people.

Proposal

When spago install isn't finding a package, it should print (with X, Y, Z being substituted):

Package X is not present in revision psc-Y you're using. Last known revision that has package was psc-Z. You can add it manually.

Steps to reproduce (in terms of terminal commands)

λ mkdir foo && cd foo
λ spago init
[…]
λ sed -i 's/dependencies = \[/dependencies = \["purescript-halogen-menu",/g' spago.dhall
λ spago install

Expected

Package X is not present in revision psc-Y you're using. Last known revision that has package was psc-Z. You can add it manually.

Actual

[error] The following packages do not exist in your package set:
[error]   - purescript-halogen-menu, and nor does `halogen-menu`
@f-f
Copy link
Member

f-f commented Sep 21, 2024

Thanks for the report!

Good error messages are a hard problem! Their author has to lay out enough information to empower the user to tackle the issue at hand, while avoiding being excessively verbose; for this reason a lot of error messages are so dense that they become inscrutable. However, the other side of the spectrum bears the risk of sounding condescending and gets old quick, which may lead to advanced users skimming through the output trying to find some signal in the noise.

In this specific case, the error message assumes that the user knows what a "package set" is. Is this a reasonable assumption? I personally think so - the very first section of the docs, the "super quick tutorial" has a short description of what a spago project contains. In there, there's a link to the relevant section of the docs "what's a package set?

I don't think the proposed error message is an improvement over the current one - a few reasons:

  • "package sets" are a broader concept than just the default ones, as you could have custom package sets, local files as package sets, etc. Again, I don't think there's a replacement for reading the docs here
  • The psc- naming convention for the versioning of the official sets is outdated - it looks like you're using the legacy Spago (versions 0.21.x), the new naming convention uses semver
  • We can do the "last set to include this package was X" for official package sets, but that doesn't work for custom ones, which should be taken into account

I wonder if a few links to the relevant docs session (about what a package set is and how to add custom packages) would be enough to help?

@Hi-Angel
Copy link
Author

Hi-Angel commented Sep 21, 2024

TL;DR: what about this:

[… here the older message that has always been printed…]
To list available packages use `spago ls packages`

In this specific case, the error message assumes that the user knows what a "package set" is. Is this a reasonable assumption? I personally think so - the very first section of the docs, the "super quick tutorial" has a short description of what a spago project contains. In there, there's a link to the relevant section of the docs "what's a package set?

It may be reasonable to assume a user at least vaguely aware of what's a "package set". Though not because they read the links you mentioned (which I, as a new user, never heard of, for example), but rather because PureScript unlikely to be the first programming language, and a user likely ± knows how packaging and versioning works in other langs.

However, it doesn't help with the problem at hand, which is the discrepancy between what a user sees on Pursuit (i.e. that a package isn't bound to specific "package set(s)", as if it's available everywhere) and what actually happens. And the links you referred to mention nothing about that.

So when a message just says "Package X doesn't exist in your package set", the thought "maybe it's a problem with the remote set" will be the last a user would think of. A user more likely to think they mistyped the package name, or maybe gotten into some sort of weird syntax issue… It doesn't help also that Pursuit for some reason writes every package name as purescript-X whereas Spago expects just X (apparently it is so frequent problem that for the case where X is found spago has a dedicated error message asking to drop purescript-).

  • The psc- naming convention for the versioning of the official sets is outdated - it looks like you're using the legacy Spago (versions 0.21.x), the new naming convention uses semver

Sorry, I am confused. Yes, indeed I am using 0.21.0 version, however I don't see how could it be legacy when it is literally the latest available release of the PureScript-based Spago rewrite 😅

I don't think the proposed error message is an improvement over the current one - a few reasons:

  • "package sets" are a broader concept than just the default ones, as you could have custom package sets, local files as package sets, etc. Again, I don't think there's a replacement for reading the docs here
    […]
  • We can do the "last set to include this package was X" for official package sets, but that doesn't work for custom ones, which should be taken into account

Oh, I see. So, at this point I read through your link and now I see the complications. The package X may or may not have been expected to be installed from The Registry, and by providing last known package set revision from The Registry we may be confusing users who expected a different source.

How about this one:

[… here the older message that has always been printed…]
To list available packages use `spago ls packages`

This would remove the hard dependency of the user to the Pursuit site, now a user can manually check what packages are available. This wouldn't help with the question "Why my package set doesn't have this Pursuit package that I clearly see?", but it at least would hint a user to seek the problem on the remote side.

I wonder if a few links to the relevant docs session (about what a package set is and how to add custom packages) would be enough to help?

In this case the specific command spago ls packages might be an excellent hint.


Idk how to hint at the discrepancy between Pursuit interface and the actual packages though.

@Hi-Angel
Copy link
Author

Hi-Angel commented Sep 22, 2024

Btw, I tried creating a commit with the message, but I can't check that it compiles because the current building documentation are obsolete. E.g. running spago bundle -p spago-bin results in suggestion to use bundle-app. But then even when it's used spago simply prints help message, without any errors. I tried skipping that step and just running spago build, but I guess it doesn't work like that because it's not finding spago.dhall file.

Hi-Angel added a commit to Hi-Angel/spago that referenced this issue Sep 23, 2024
Currently there exist confusion due to Pursuit now showing package
sets that include a package. IOW it always looks as if every package
on Pursuit available on every "package set" from the registry. As
result, when a user receives error message from Spago that says that a
package wasn't found, unless a user already knows this situation, they
unlikely would think it's a problem on the remote side rather than
with syntax or something similar.

But on the `spago` side we can reduce confusion by showing a user
a message hinting that it is possible to enlist available packages
with `spago ls packages`.

Fixes: purescript#1287
@Hi-Angel Hi-Angel linked a pull request Sep 23, 2024 that will close this issue
3 tasks
@Hi-Angel
Copy link
Author

Anyway, I used lsp server to check that there isn't syntax errors, and CI has build checks as well, so I sent a PR.

Hi-Angel added a commit to Hi-Angel/spago that referenced this issue Sep 23, 2024
Currently there exists confusion due to Pursuit now showing package
sets that include a package. IOW it always looks as if every package
on Pursuit available on every "package set" from the registry. As
result, when a user receives error message from Spago that says that a
package wasn't found, unless a user already knows this situation, they
unlikely would think it's a problem on the remote side rather than
with syntax or something similar.

But on the `spago` side we can reduce confusion by showing a user
a message hinting that it is possible to enlist available packages
with `spago ls packages`.

Fixes: purescript#1287
Hi-Angel added a commit to Hi-Angel/spago that referenced this issue Sep 24, 2024
Currently there exists confusion due to Pursuit now showing package
sets that include a package. IOW it always looks as if every package
on Pursuit available on every "package set" from the registry. As
result, when a user receives error message from Spago that says that a
package wasn't found, unless a user already knows this situation, they
unlikely would think it's a problem on the remote side rather than
with syntax or something similar.

But on the `spago` side we can reduce confusion by showing a user
a message hinting that it is possible to enlist available packages
with `spago ls packages`.

Fixes: purescript#1287
Hi-Angel added a commit to Hi-Angel/spago that referenced this issue Sep 24, 2024
Currently there exists confusion due to Pursuit not showing package
sets that include a package. IOW it always looks as if every package
on Pursuit available on every "package set" from the registry. As
result, when a user receives error message from Spago that says that a
package wasn't found, unless a user already knows this situation, they
unlikely would think it's a problem on the remote side rather than
with syntax or something similar.

But on the `spago` side we can reduce confusion by showing a user
a message hinting that it is possible to enlist available packages
with `spago ls packages`.

Fixes: purescript#1287
Hi-Angel added a commit to Hi-Angel/spago that referenced this issue Sep 24, 2024
Currently there exists confusion due to Pursuit not showing package
sets that include a package. IOW it always looks as if every package
on Pursuit available on every "package set" from the registry. As
result, when a user receives error message from Spago that says that a
package wasn't found, unless a user already knows this situation, they
unlikely would think it's a problem on the remote side rather than
with syntax or something similar.

But on the `spago` side we can reduce confusion by showing a user
a message hinting that it is possible to enlist available packages
with `spago ls packages`.

Fixes: purescript#1287
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants