[Mageia-webteam] Proposal for maintainers database API

[nicolas vigier]

Here is a proposal for an API that can be used on the maintainers
database, with the list of URLs and what they should do :

***
An html page with the list of all packages, and their maintainer :
http://maintdb.mageia.org/packages.html
As we have many packages, the page will be long, so maybe we want to
split the list by first letter of package name :
http://maintdb.mageia.org/packages_a.html
http://maintdb.mageia.org/packages_b.html
http://maintdb.mageia.org/packages_c.html
...
The list of all packages and their maintainers, in text format :
http://maintdb.mageia.org/packages.txt
With the output like this :
package1:maintainerlogin1
package2:maintainerlogin2
package3:maintainerlogin3
...

***
An html page to show the maintainer of one package (with
[packagename] replaced with the name of a package) :
http://maintdb.mageia.org/packages/[packagename].html
The same in text format :
http://maintdb.mageia.org/packages/[packagename].txt
With output like this (only one line):
packagename:maintainerlogin
If the package is unmaintained, it appears like this :
packagename:nobody
If the package does not exist, an empty file is returned.

***
The list of maintainers (all maintainers who maintain at least one
package) :
http://maintdb.mageia.org/people.html

***
The list of packages maintained by someone (with [loginname] replaced by
a login) :
http://maintdb.mageia.org/people/[loginname].html
And the same in text format :
http://maintdb.mageia.org/people/[loginname].txt
With the same format for output :
package1:loginname
package2:loginname
package3:loginname
...
If the login does not exist, an empty file is returned.

***
The list of unmaintained packages :
http://maintdb.mageia.org/people/nobody.html
And the same in text format :
http://maintdb.mageia.org/people/nobody.txt
With this output :
package1:nobody
package2:nobody
package3:nobody
...

***
The URL to add a package, used by the buildsystem when a package is
uploaded on the repository :
https://maintdb.mageia.org/admin/setnewpackage
Protected with basic http authentication (with a login/password that was
set in maintdb or apache configuration).
Accessed with a POST request and the following two arguments :
package: [packagename]
maintainer: [maintainername]
If the package already exists in the database, it is not updated.

***
The same as the previous URL, but the package maintainer is updated when
the package already exists in the database :
https://maintdb.mageia.org/admin/setpackage

---------

Maintainers also need to be able to drop maintainership of their
packages, and take maintainership of unmaintained packages. For doing
this, I think there is two solutions :

1) On the html pages, maintainers are able to authenticate using
   their login and ldap password. When authenticated, the packages
   maintained by nobody have a link "take maintainership". And the
   packages maintained by the authenticated user have a link "drop
   maintainership".

2) The website does not allow changing maintainership. Instead, we add a
   command in mgarepo to do it. And to do it, mgarepo connects to valstar,
   is authenticated by ssh, and run a script on valstar to request the
   change. This script has access to the admin password and will connect
   to the "admin/setpackage" URL to update the package maintainer.

I think the 2nd solution is better, because it allows scripting, for
example to drop/take maintainership of all packages using a regexp.
You manage maintainership using the same tool used to submit packages.
And I think it's maybe less work to implement it as it avoids adding ldap
authentication in maintdb, and creating pages to do the updates. Maybe
we also don't need html pages at all in that case.

And I think that's all we need for the first version.

If we compare with the maintainers db website used at mandriva, their
version also has :
 - media name for each package, with pages to list packages from only
   one media
 - a search box to search for a package
 - links to bugzilla for each package
But I don't think we should store the media name in maintdb. And to
search for packages, see media names, find bugs, we should use sophie
or mageia-app-db instead. Actually users who want to see the maintainers
of packages should probably also use mageia-app-db or sophie.

maintdb should mainly be used in the following cases :
 - by sophie, mageia-app-db and other package databases which want to show
   maintainers of packages. They download the full list of packages and
   maintainers every day (or hours) from the text file, to synchronize
   with their database.
 - by bugzilla if we want to assign bugs automatically to maintainer
 - by build system or svn, for example if we want to send emails to package
   maintainers when someone else commits to their packages
 - by other tools which may need it ...



For version 2 or later, we can also have those features :
 - a changelog page, to see who took/dropped maintainership of which
   packages. Maybe with an rss too. And a text files containing the
   changes from the last 2 days (to avoid downloading the full list, if
   you only want to synchronise).
 - an URL to remove package (with admin password):
   https://maintdb.mageia.org/admin/removepackage
 - maybe support for groups and/or multiple maintainers

For groups, we'll first have to see where we want to store them. But
for the maintdb text output, we could use something like this :
package1:maintainer1,maintainer2,maintainer3
package2:%group1
package3:%group2,maintainer4
...

And with the following pages to list packages maintained by a group :
http://maintdb.mageia.org/groups/groups/[groupname].html
http://maintdb.mageia.org/groups/groups/[groupname].txt