Re: [ELPA] New package: repology.el (v4)

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

As announced a few days ago, and with the guidance of Stefan Monnier,
I tweaked "repology.el" so it is somewhat aware about freedom, and
cautious about what it displays.

TL;DR: it is currently located at <https://elpa.gnu.org/devel/repology.html>.

Here is its current commentary section. The third and fifth paragraphs
are of particular interest for the discussion.

    This package provides tools to query Repology API
    (<https://repology.org/api>), process results, and display them.
    
    The results of a query revolve around three types of objects:
    projects, packages and problems.  Using this library, you can find
    projects matching certain criteria, packages in a given project,
    and possible problems in some repository.  See `repology-search-projects',
    `repology-lookup-project', and `repology-report-problems'.
    Projects-related requests are limited to `repology-projects-limit'.
    All requests are cached during `repology-cache-duration' seconds.
    
    By default, only projects recognized as free are included in the search
    results.  You can control this behavior with the variable
    `repology-free-only-projects'.  The function `repology-check-freedom'
    is responsible for guessing if a project, or a package, is free.
    
    You can then access data from those various objects using dedicated
    accessors.  See, for example, `repology-project-name',
    `repology-project-packages', `repology-package-field', or
    `repology-problem-field'.
    
    You can also decide to display (a subset of) results in a tabulated
    list.  See `repology-display-package', `repology-display-packages',
    `repology-display-projects' and `repology-display-problems'.  You
    can control various aspects of the display, like the colors used
    (see `repology-status-faces'), or the columns shown (see
    `repology-display-packages-columns',`repology-display-projects-columns',
    and `repology-display-problems-columns').  When projects or packages
    are displayed, pressing <RET> gives you more information about the item
    at point, whereas pressing <F> reports their "freedom" status.
    
    For example, the following expression displays all outdated projects
    named after "emacs" and containing a package in GNU Guix repository
    that I do not ignore:
    
       (repology-display-projects
        (seq-filter (lambda (project)
                      (not (member (repology-project-name project)
                                   my-ignored-projects)))
                    (repology-search-projects
                     :search "emacs" :inrepo "gnuguix" :outdated "on")))
    
    Eventually, this library provides an interactive function with
    a spartan interface wrapping this up: `repology'.  Since it builds
    and displays incrementally search filters, you may use it as
    a template to create your own queries.

The library distinguishes between three categories of freedom for
projects/packages: free, non-free, and unknown. Out of the 200.000
projects from Repology, it currently considers that about 73.000 are
free, 300 are non-free, and the rest is unknown.

Out of the box, the interface now only displays projects _most likely
free_ (more in this below). It is also possible to configure it so it
displays both free and unknown categories, or everything.

The commentary section in "repology-license.el" explains how freedom
state is obtained:

    This library provides the `repology-check-freedom' function, which returns
    t when a package or a project can be considered as free, nil it is
    identified as being non-free, and `unknown' otherwise.
    
    The decision is made by polling a number of "Reference repositories",
    defined in `repology-license-reference-repositories'.  If the ratio of
    "Free" votes is above `repology-license-poll-threshold', the project is
    declared as free.
    
    In order to see the results of each vote, and possibly debug the process,
    you can set `repology-license-debug' to a non-nil value.

Currently, reference repositories are: Debian, Fedora, OpenSUSE, Gentoo,
Mageia, along with all FSF-endorsed distributions known to Repology: GNU
Guix, Hyperbola, Parabola, PureOS, and Trisquel. I also added GNU ELPA
as a specialized repository.

The poll threshold is set to 0.5, so a package/project needs a strict
majority of "Free" votes to be considered as free. As explained above,
it is possible to look at the vote results to understand the final
decision for each project.

I hope this is now more in line with GNU expectations. Let me know if
you have questions, or suggestions.

Regards,
-- 
Nicolas Goaziou