For package popularity, both gitlab and github already support tools to assess this in the form of stars. I would love to see a star count if available.
I would also like revdep count to also be displayed up front: even though it’s biased towards libraries, it is important information, as it means the package is being heavily used.
Finally, the last update date is very important information. A package last updated 10 years ago will likely not be integrated well into the ecosystem, may have security issues, and is also likely to lack the more recent enhancements in terms of performance and readability. Even a stable library requires minor updates to keep up with recent ecosystem changes. A long time gap usually indicates abandonment.
I dislike the README idea mostly on the grounds that a lot of proposals are choosing README.md and Markdown has a) a lot of limitations for documentations, and b) so many forks (“flavors”) that it would be a nightmare to try to support everyone’s favorite option. “Renders fine on my GitLab page, why doesn’t feature X work on ocaml.org”. It also limits alternatives like AsciiDoc, reStructuredText, Djot, etc. Some code forges allow querying the rendered README via API (I know at least sr.ht does), but you can still end up with inconsistencies in CSS classes per forge down to the syntax highlighter (GitLab uses Rouge, SourceHut Pygments, etc.). I also agree with the original rebuttal that the content in READMEs varies wildly across projects that you don’t know you’ll get—including video files on some. There’s also been a feature creep issue where a lot of READMEs have morphed into RENDERMEs where they are unreadable as plaintext, filled with HTML and image-only badges that don’t help you read about a project when opening the file. There’s already a spot to link to one’s docs that could link to separate docs or one’s README.
RE: Stars
A few months back there was an issue with a projects that got to the Hacker News front page. When you linked your Microsoft GitHub account with the site, the project automatically starred itself. This ended up triggering the systems at Microsoft GitHub to ban the user that got locked out of their account. Star hacking and gamifying popularity contest are an issue. The amount of stars a project has should only be taken with a grain of salt as it doesn’t correlate with code quality. I would vote against including such information because I think it leads to too many users worrying about how popular their projects are and it also would disincentivize folks that want to use SourceHut, Codeberg, or self-hosting cgit, Forgejo—or not using Git at all in favor of Mercurial, darcs, Pijul, etc. Remember that Git is distributed version control, and centralizing on a handful of platforms goes against one of the core features. ForgeFed is looking to allay some of these issues hooking one’s forge up to the Fediverse to decentralize these features, but will likely not be on by default and not everyone wants their code to be a part of a social network like what ForgeFed is proposing and Microsoft GitHub and GitLab are currently offering.
It is very helpful to see you all spell out the consequences of possible choices and lay out the underlying reasons that led to the status quo. We are looking to uncover the most reasonable solution that will make sense for the years to come where we see the ecosystem flourish and where people can build more and more great things with OCaml.
I would hate if we ended up having to move things around again in a few months or years, only because we put up an interim/shortcut solution now. There is a real cost to changes we make here: the content of the package’s “landing page” on ocaml.org may influence where you place which information in order to provide a great experience for onboarding users to your packages.
I will summarize all points and considerations brought up next week on Wednesday in this thread.
I think this is looking for a theoretical issue when the practical day-to-day usage of stars is fine. github and gitlab provide user verification for free. This allows them to come up with a popularity measure that has value. Is it a perfect measure? Of course not, nothing is. But all other things being equal, it lets us have some measure of the library or application’s true user count and satisfaction levels.
I don’t think we should aggregate multiple measures into some kind of score. Simply provide the facts as they are. This is the number of stars on this package (if available). This is the number of revdeps. This is the number of downloads, and this is when the package was last updated. Each one of the fields should ideally be sortable. That’s it.
Thanks for taking the task of summarizing. Would it be possible to also vote (a poll) on what goes on the overview? Not so much “which do you prefer” questions but “would seeing XXX on the overview significantly improve your OCaml development experience” or (if technically possible) “what are the top 3 things you want to see on the overview”.
I haven’t heard it mentioned yet, but I’d also love if the overview includes the findlib library names which today you have to click on the Documentation link to find. I find myself looking for that information the most frequently. But I may be unique.
Ok, so that was quite a bit to digest. Here’s a summary:
1- Debate about package quality metrics
Having “last published” and publication date in general displayed on the page might interfere with the visibility of stable packages that do not need improvement.
Ideas for other metrics:
(manual) self-assessment of package author. (Code quality, performance, maintainability, evolution, version >= 1.0.0 etc.)
(manual) Maintenance-related tagging: signal the need for additional maintainers, signal that a package needs maintenance
(automated) Signal broken packages.
(automated) Metrics from external sourecs: e.g. GitHub Number of issues / pull requests / star count
Contrapoint: supporting all options, including popular open source self-hosted optionsis a huge work item, and choosing just a few is inherently unfair
(automated) Weekly download statistics
2- Debate about displaying or not displaying README / opam description / index.mld on package overview:
Since README is publicly displayed on GitHub/GitLab etc, many people currently use it as a “public landing page” of the package.
Essentially, these other services encourage writing README in a certain way - in order to establish proper context within that other service
Challenge: Ideally, package authors should not have to repeat the same info in several places.
Aspects to consider wrt README:
different renderers on different sites (e.g. GitLab, GitHub, SourceHut, Pygments, etc.) support different markdown features
Nowadays more and more READMEs contain images or even videos, as well as tons of badges
Ideas:
Show a collapsible README on package overview
Instead of rendering README on package overview: add a link to the README (but where to, to the hosted repository or to ocaml.org’s rendition of README?)
Index.mld and other .mld files could be displayed instead of README. Additionally, links for API documentation and tutorials
Note: if you don’t specify an opamsynopsis and/or description yourself, dune-release derives those from your README as described in Looking for Ideas for the Package Overview Page on OCaml.org - #40 by dbuenzli. However, when you want to link somewhere from within the $(DESCRIPTION) block, that will not work at the same time on GitHub as well as in other documentation contexts (e.g. locally-built offline documentation vs ocaml.org vs GitHub).
3- Playground functionality
“Tested examples”, i.e. ability to write code sections in the package docs that will be executed as tests during the documentation build - helps package users assess whether the documentation is up to date and makes it easier for package authors to update the docs when functionality changed
Ability to run code examples from packages in the playground
“Runnable examples” like Testable Examples in Go - The Go Programming Language - ability to write code sections in the docs that will (1) run as tests during the package documentation build step, and (2) render as an “inline-playground” within the surrounding documentation page
4- Other Feedback/Ideas
Allow URLs like https://ocaml.org/p/{PACKAGE}.{VERSION}
On package version dropdown - Add published date for each version
It would be nice to have badges for your package to display on the README so that the package repository looks attractive on the version control website where it is hosted
Package overview should show all the findlib library names
Dependencies, Reverse Dependencies and Conflicts need more space, as they can be quite narrow and tall
I remember once seeing an OPAM build matrix page where the rows were packages and columns were OCaml versions. Could this existing data be presented on the package page? Whether a package builds could indicate its maturity and maintenance status without biasing packages with new releases over stable old packages.
I’m not sure if ‘package builds’ could act as a stable quality indicator. A package may build today but, many packages don’t have version bounds on their dependencies, and could easily break tomorrow. There are examples of version bounds being added to packages in the opam repository to fix breakages.
