develooper Front page | perl.cpan.workers | Postings from May 2015

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

Thread Previous | Thread Next
From:
Kent Fredric
Date:
May 7, 2015 23:40
Subject:
Re: Documenting best practices and the state of ToolChain guidelinesusing CPAN and POD
Message ID:
CAATnKFBniEfPQTdRR80nYj7Ucfbp-xL5jJH7NNLaKjVpc5DXuA@mail.gmail.com
On 7 May 2015 at 23:37, Philippe Bruhat (BooK) <philippe.bruhat@free.fr>
wrote:

>
> It lives in the book/publishing branch:
> https://github.com/book/CPANio/tree/book/publishing
>
> The current reference documents are obtained from these repositories:
> - https://github.com/neilbowers/history-of-cpan.git
> - https://github.com/Perl-Toolchain-Gang/toolchain-site.git
>
> Each document has a "fork me on github" link pointing back to it,
> and so does the table of content (pointing back to the project instead
> of individual files).
>
> The configuration lives here:
> https://github.com/book/CPANio/blob/book/publishing/cpanio.yml
>
> New documents in the source repository are published automatically
> (see include/exclude for ways to ignore documents).
>
> Unless someone objects, I'll put this live in a day or two.


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 )

I like that its got aggregation options, and that it can pull from
different locations.

So can we talk about layout and authorship concerns?

1. How often do aggregated repositories get sourced?
2. How easy is it to stipulate adding more repositories?
3. What mechanism is there for restricting what an automated update pulls
so that only "finalised" docs are published, and not drafts?
4. How exactly are the sourced documents layed out
5. How are we going to optimise our policy layout so its clear which
policies are newest
6. How are we going to optimise our policy layout so its clear when a
policy was last modified
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.

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.

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.

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

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.

-- 
Kent

*KENTNL* - https://metacpan.org/author/KENTNL

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About