Open andrewufrank opened 5 years ago
Thanks for the report.
Error handling / reporting is indeed a sore spot that I would like to see improved, and so is the CLI.
Some details deserve explanation:
(suggestion - it would probably more instructive if the last commit was included in the version)
I agree; however, this has a few drawbacks. First of all, if you build an uncommitted source tree, you would still have to append some generic tag like +modifications
to the version, so it'd still be a bit of a mess. Then, adding the actual commit hash to the version number introduces an implicit build dependency on git, or, more specifically, on the build happening on a git working copy, which isn't necessarily the case (e.g. if you build from a downloaded tarball). We still have this dependency, but we can gracefully and silently recover if it isn't met - essentially, if we're not in a git repo, then we'll assume that whatever version number the Cabal file gives us is exactly what we're building. Further, in a realistic scenario, a deployed binary on a production system is generally going to be a "proper" version (i.e., some properly versioned release without any additional modifications), so there is very little added value in going through the hassle of including the actual commit hash in the reported version number.
Actually, after checking the sources, I remembered that we are already doing exactly what you're asking:
0.6.0.0
).0.6.0.0
)0.6.0.0 (implement-foo-feature)
)+git-
plus the git commit hash (e.g. 0.6.0.0+git-1a5afdf35dd247ac14e5d2f02a4b11c07a3c8989
)git status --porcelain
produces nonempty output), +modifications
is appended to the version string.This means that your 0.6.0.0+modifications
build is based on a git working copy at tag 0.6.0.0
, with either local modifications or non-ignored untracked files in the working copy.
I followed the 001-getting started instruction and when I run sprinkles 5000 i get
Ah, terrible shame - the CLI syntax got changed at some point. Previously, sprinkles could only really do one thing, namely, serving the current project, and you would pass options to control the details (which HTTP backend to use, which port to run on, etc.). But with the introduction of the -bake
command, this got changed, and so now if you want sprinkles to actually serve the project, you have to explicitly pass -serve
. The whole CLI options could use an overhaul, but I'm slightly reluctant to introduce breaking changes here. In any case, I updated the relevant line in the Getting Started guide.
it is not server, as one might expect!
It's a verb, just like "bake". sprinkles -serve 5000
means "Sprinkles, please serve this project on port 5000", just like sprinkles -bake ./baked
means "Sprinkles, please bake this project and store the result in the baked
subdirectory".
but nothing shows (not even 404). At least an useful error message would be appreciated when one first works with a program.
Sprinkles should very much produce a bare-bones 404 page, saying something like "Not found" in plain text, when the given path doesn't resolve to any rule, or when the matching rule cannot load a required data item. Likewise, if there is some sort of error while handling the request, like a syntax error in a template, or a crash in a data backend, Sprinkles should serve a default plain-text 500 page. Exposing any more error information than that to the browser is generally considered a security problem (and also a bad thing to do for other reasons), and is best avoided entirely. I do agree however that the error log should contain more useful information, and that it would be helpful to configure more verbose error logging in the tutorial.
Perhaps it would be better to have as a master branch a version that certainly runs and the development on identified branches and tell in the 001 instructions, which version they were tested with.
The tutorial is part of the git source tree, and the intention is that it matches the version of whatever commit you are looking at. I must admit however that I do not check the tutorial for every commit, or even every release, so it is very possible to be incorrect. Sorry about that.
I later found the my error: the home.markdown had a mistyped extension (makrdown) which explains that nothing was found. still a helpful error message would be appreciated.
Agree; logging which exact file sprinkles failed to find might be convenient. There is one caveat with this, which is that it isn't always obvious whether a file is missing by accident or on purpose. Sometimes, you want to load a file if it exists, and silently get null
in its place if it doesn't. If the file is in the required
list for that rule, then it is obvious that silent null
isn't desirable, but otherwise, sprinkles can't tell if the file should have been there.
the command should have a -h and a --help text, which tells what functions are possible (I think this can be created automatically with CmdLineUtilities.UtilsProcessCmd).
Yes, --help
should absolutely be supported. The main reason it isn't is negligence on my part. Due to the way the argument parser works, it cannot be created automatically, but that's a lousy excuse. An overhaul should either add help text manually, or switch to something like argparse-applicative
, which gives you --help
for (almost) free.
It seems to be customary to have -v and --version switches, but not -version.
Again, a bit of negligence here. In principle, the convention for sprinkles args is to have GNU-style single-dash keyword args, but for mere convenience, and to avoid confusion, we should support -h
, --help
, -v
, and --version
as well. In fact, I'm willing to reconsider the choice entirely, the only valid argument against would be backwards compatibility.
EDIT:
Actually, I just checked; --version
and -v
should also just work. If they don't, then please do file a new bug report specifically.
I have just installed from github a727a02 on a debian stretch system. the version is
(suggestion - it would probably more instructive if the last commit was included in the version)
I followed the 001-getting started instruction and when I run
sprinkles 5000
i getwhen i used
sprinkles -serve 5000
I get on opening localhost:5000 (it is not server, as one might expect!)but nothing shows (not even 404). At least an useful error message would be appreciated when one first works with a program. Perhaps it would be better to have as a master branch a version that certainly runs and the development on identified branches and tell in the 001 instructions, which version they were tested with.
I later found the my error: the
home.markdown
had a mistyped extension (makrdown
) which explains that nothing was found. still a helpful error message would be appreciated.some comments: the command should have a -h and a --help text, which tells what functions are possible (I think this can be created automatically with CmdLineUtilities.UtilsProcessCmd). It seems to be customary to have -v and --version switches, but not -version.
interesting but challenging project!