[I added a specifier to the subject]
On 28/01/16 23:31, Ryan Day wrote:
To provide a standard README file for each rumprun package, a template
system should be implemented. An existing structure that we could loosely
follow is the pkgsrc system. Pkgsrc generates READMEs from variables in a
Makefile.
Yup, more infrastructure for rumprun-packages is in general is a good
thing, and need to start from somewhere.
DISTNAME= <pkg name>-<version>
CATEGORIES= <following pkgsrc categories>
MASTER_SITES= http://www.all.the/files/
MAINTAINERS= "Full Name" <[email protected]>,"Distinguished Full Name,
Esq." github: @fnesq
HOMEPAGE= http://url.to.site.homepage
COMMENT= This library is linked to by other rumprun packages
LICENSE= to ill
NOTES= NOTES
EXAMPLE= EXAMPLE
- - - - -
I've included CATEGORIES, even though rumprun packages don't have them.
Maybe it isn't needed yet.
My experience with categories from pkgsrc has been that the "misc"
category will eventually have the most packages.
Taxonomy was a great tool before powerful electronic computers were
invented ;)
So, my vote is to skip categories, and instruct users to use either grep
or a web service to search for what they want. I'm guessing the common
search problem, anyway, is "can I run X on Rumprun", not "which programs
do Y".
I've added the EXAMPLE variable, which would pull from a file. Most rumprun
packages have an example included in the README.
I think that would be better served by a link to the relevant part of
the wiki. I can't yet define "relevant" since we didn't finish the
other thread, but some sort of wiki link in any case. Just so that this
mail is self-contained, my initial thinking was an anchor to the
Packages TOC. That way, if there are many pages relevant to a package,
you can get a glimpse of all of them (e.g. basic python usage and using
flask on python). Alternatively, we can add two links, one to the TOC
and one to the base page for the package.
I've added the NOTES variable, which would also pull from a file. Some
packages may have additional information that the user needs to know about.
Redis only works with one type of persistence, for example. Mysqld disables
threads, as another example.
Is NOTES something that should be pulled from a file, or should we
enforce keeping it simple by requiring it's specified inline in the
Makefile?
# Overview of ${DISTNAME}
${COMMENT}
Maybe this could "$distname is $comment", just to avoid having to
duplicate that wording in every COMMENT?
Source files are retrieved from [${MASTER_SITES}](${MASTER_SITES}). More
information about the package can be found at [${HOMEPAGE}](${HOMEPAGE}).
Is the tarball location relevant? How many percent of users would want
to click it manually?
This package uses the ${LICENSE} license.
# Maintainer
* ${MAINTAINER[0]}
* $(MAINTAINER[1]}
The information for maintainers might take some more tuning for how to
make it easy to specify in the Makefile.
# Example
${EXAMPLE}
As mentioned earlier, that's probably better served by a wiki page.
We could also include standard links in the READMEs pointing to the FAQ
and build-rr tutorials.
Hmm. Inspired by the above sentence, maybe the README could say
something like "package of <pkgname> for the Rumprun unikernel[link]".
That would increase our search engine relevance, and still give people
who find us from a search engine some way of discovering how they're
actually supposed to use the package.
I'm not sure it's necessary to link every single howto from every page.
Then again, I never had the experience of discovering this stuff via a
link, so I have no idea. Comments from people who recently discovered
rumprun-packages would be valuable.
This is getting rather long. Any thoughts, obvious problems?
I'd say that we don't yet have so many packages that this needs to
implemented "atomically". IMO, changes toward the direction you propose
can be initiated (but wait a day or two for other opinions). Though, I
guess nailing down the packages wiki is the roadblock, since the heavy
lifting is getting the examples etc. into another place so that you can
actually generate the READMEs without losing existing information.
