Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD

On Fri, May 08, 2015 at 11:39:59AM +1200, Kent Fredric wrote:
> 
> Ok, this is an OK starting point for me. Its not *my* ideal because there's
> of course the audience who have PAUSE keys and not github accounts ( and
> don't want them ), but thats more a side note at this moment ( And was
> inherently a likely contribution limitation to my suggestion w/ other
> repos, just not their own )

No one needs to register anywhere to contribute to a git repository:
if they want to go the hard route, git format-patch and git send-email
are their friends.

> I like that its got aggregation options, and that it can pull from
> different locations.
> 
> So can we talk about layout and authorship concerns?

The following represents what cpan.io does now. It was put together
in half a day. It's open source, and I welcome pull requests. So it's
flexible. We can modify it to suit whatever need we have.

> 1. How often do aggregated repositories get sourced?

every hour.

> 2. How easy is it to stipulate adding more repositories?

Send a pull request for updating cpanio.yml to http://github.com/book/CPANio

> 3. What mechanism is there for restricting what an automated update pulls

I've put a few restrictions in the form of 'include' (defaults to *),
'exclude' (defaults to nothing), and recurse (defaults to don't).

> so that only "finalised" docs are published, and not drafts?

it can pull from a named branch, so you could have a "final" branch
for those documents.

> 4. How exactly are the sourced documents layed out

Simple template with basic HTML around.

For now, only markdown format is supported, but I intend to support
additional formats as needed.

> 5. How are we going to optimise our policy layout so its clear which
> policies are newest

Docs are listed in the order the repositories are listed in the yaml file,
and then by creation date.

> 6. How are we going to optimise our policy layout so its clear when a
> policy was last modified

The bottom of each document has a "Last modified by" line, based on the
last commit on that file.

> 7. How are we going to optimise our policy layout so its clear from a users
> perspective what  changes have happened recently in any policy.
> 
> Point 5 is easily solved by the numerical sequencing we covered earlier.
> 
> Points 6 and 7 are hard, but are presently satisfied by metacpan.

I suppose we could have the date in the table of content, or even
a "last modified" page. Generating a RSS file is also possible.

> Keep in mind I'm trying for a solution here that we can apply to cpan.io
> that covers project policies like Moose/DBIC/Catalyst as well as author
> policies like Author::RIBASUSHI.

I'm not sure author policies would fit in CPAN.io, but I guess we need
to see how this evolves.

> With regards to the latter half, we may be interested in a system where an
> author can ship to both CPAN and integrate with the cpan.io website, or do
> only one of the two, using the same codebase.

For now, the authors had nothing special to do to have their documents
supported on CPAN.io. I would be nice if it could stay this way.

I tested with toolchain-site to show up the Oslo and Lancaster consensus
documents, and they showed up just fine.

I don't foresee any special difficulty in publishing a set of pod
documents living on CPAN.

> Or they may wish to simply host their policies on their own somewhere.

That's probably what most people do at the moment.

> Either way, we should pave a path for interop to make it easy to do the
> right thing.
> 
> 
> I would probably also consider a JSON/YAML file being listed in each policy
> root that acheives some of the above concerns:
>   - associates policies with tags
>   - define desired policy presentation order
>   - define visibility of policies at the top level ( ie: so that deprecated
> policies don't list on the main lists )
> 
> etc.

Good idea! This special config file should be optional, though.

-- 
 Philippe Bruhat (BooK)

 Sometimes only by losing the battle can you win the war.
                                   (Moral from Groo The Wanderer #117 (Epic))