I discovered a typo in the OCaml manual.
The arguments of a sum-type constructors
and probably should read instead:
The arguments of sum-type constructors
but for some reason there’s no way to file an issue right on that repository?
You either want to make a pull request with the change on GitHub or file the issue at https://caml.inria.fr/mantis
I now remember that bit. I tried to get a Mantis account a while back and failed.
It’s a shame, it would be nice if casual users could still file small bug reports on Github. This adds a level of complexity that probably means some people get discouraged from filing a small bug report.
(In the current case I’m interested enough that I’ll figure out where that particular documentation is and file a pull request etc., but that isn’t as easy as just filing the bug would have been. Others who are less interest might have just walked away rather than report a single extra “a”.)
The manual chapters are in TeX files - that one is https://github.com/ocaml/ocaml/blob/trunk/manual/manual/refman/exten.etex
I completely hear you on the problem of Mantis - the dev team is quite keen to move away from Mantis, it’s just slow-going implementing the change.
I filed a pull request: https://github.com/ocaml/ocaml/pull/1734
By the way, generally, I find the “extensions” section to be a little odd. If OCaml was defined by a language standard and the implementation had extra features, it would make a lot of sense, but since it is really defined by the implementation, these aren’t “extensions”, just new features, and anyone new learning about the language probably wants to learn about them as they’re learning the other logically related features.
These things should probably be documented in the more logical place in the manual, with a “New Features” section of the manual that perhaps redundantly explains them so that old timers don’t need to hunt around to learn what has been added.
But this is a new and different topic.
the dev team is quite keen to move away from Mantis
I don’t think it is as cut and dry as that. The Github interface lacks quite a lot of the functionality of Mantis, and I for one would be sad to see us switch.
By the way, generally, I find the “extensions” section to be a little odd.
Yeah, there are quite a few things in there that really shouldn’t be. Although some things, like recursive modules, are deliberately in there because their semantics are likely to change backwards incompatibly just as soon as someone figures out what on earth they should be.
Github is constantly working on improving their issues interface. Care to list which missing features you like in particular?
It’s just generally not very good. It is more awkward for browsing the issues at a glance, the search is less sophisticated for trying to find an issue you vaguely remember, and it doesn’t provide a convenient view of the issues relevant to you.
Github’s issues and pull requests have a fairly sophisticated query language. You can do things pretty easily like asking “what are the closed issues I’ve submitted” and the like, and it has nice search mechanisms.
I would be rather in favor of moving to Github (because people are increasingly reluctant to use Mantis, although it is a good tool), but I think that people may not realize (1) the difficulty of migrating a decade of bugtracker use and (2) how bad searching github for content is.
For Mantis, I just use google with “site:caml.inria.fr/mantis foo bar”, and I can find the bug (or feature proposal) I am vaguely remembering quite easily. Github seems to actively block Google from indexing their website’s content, which results in extremely poor searchability.
Note that this is not just a bugtracker issue; I am actually worried about the loss of collective memory that comes from using an unsearchable tool – same with writing Facebook posts instead of web-facing blog posts.
Suppose for example that I want to find the mantis MPR that led to the “exception patterns” feature, site:caml.inria.fr/mantis exception patterns, the result is in the middle of the first result page on my machine: MPR#6318: Extend try with “success” handling. Notice in passing how the description of an issue usually uses fairly different wording from what we come to remember of it, as the naming improves as our understanding matures.
On the contrary, suppose I want to find the more recent github GPR that led to a rewrite of the recursive-value check in the compiler; the Google query site:github.com/ocaml/ocaml/pulls let rec value check returns no result, and using is:pr let rec value check is disappointing : it points to some related PRs, but not the one I am looking for on the first page – it does show up if I manually add the “is:merged” modifier, near the bottom.
As regular users of the bugtracker and PR tracker, the way we adapt to this state of affairs is to copiously cross-link everything; we try to systematically mention related older related issues within discussions of younger issues, to shortcut the usage of the search feature.
One could just keep both. Allow users to file casual bug reports (like the one I wanted to file) on github, and caution them (which you can do) that all significant projects are tracked on Mantis instead. I’m not sure this is ideal, but it would allow more bug reports to be made by people who are not feeling overly invested in spending a lot of time signing up for things so they can report a bug.
This is a very good point that I was not aware of. Github’s
robots.txt only lets google index a
master branch. I assume the reason for not indexing PRs and issues is that they’re not under the control of the author, but there should be a way to opt in.
This is the other killer feature that’s surprisingly missing from github. This request has been wanted for at least 3 years – to be able to view all issues to which you’ve subscribed. Right now, you have to comment on an issue or at least upvote it to be able to find it easily later.
I’ve emailed github support about the first issue. Perhaps they have a solution for us.
By-the-by, OCaml issues have now been migrated to GitHub as the canonical issue tracker: https://github.com/ocaml/ocaml/issues