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

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

Thread Next
Kent Fredric
May 6, 2015 06:04
Documenting best practices and the state of ToolChain guidelinesusing CPAN and POD
Message ID:
This is something that has bothered me for a while.

We have a lot of standards and guiding principles, but a lot of it is all
in our heads, wisdom one can only get by talking about it on toolchain,
and/or breaking things and getting yelled at.

In that vein, we need some sort of Canon set of documentations, written and
maintained by toolchain themselves, articulating how things /should/ be
done as far as toolchain are concerned, without any sort of requirement
that people adhere to it, unless they want to make toolchain happy.

Python have something similar to what I propose, PEP standards. Shit, I
think I even saw some group for PHP define some set of standards for
certain things(!!!! They're learning and getting organised, quick, kill
them before they breed)

Its also sad we don't really have any canonicalised representation of any
toolchain agreements that have been established at hackathons, they're
basically invisible or hiding on individual members blogs. As is the best
practices for various problems also hidden on various blogs ( see also
version numbers should be boring )

And this creates substantial problems for discovery and recall, as well as
having a significant point-of-failure if any of the individuals maintaining
those auxiliary sites get eaten by a SIGBUS

As such, I propose a very rudimentary idea:


This is the top namespace


This is an index of various standards and guidelines


Where <name> is \d{4}_\w+ , for example 0001_Versions

Numericalization is intended to make it clear which standards are "newer"
and which are "older" instead of just having a pure Alnum sort.

Toolchain::Standards itself should be an index of the standards grouped
under several headings, with a short brief under each.

Understandably, this is not necessary for metacpan which will show
abstracts naturally, but we may want briefs larger than a standard
abstract, and we want to optimise for offline consumption also.

There would also be a proviso for deprecating or suspending a standard if
it fell out of use, and this organisation would also be helpful there.

( As well as having an index of articles that pertained to specific
subjects and/or were decided on by various QAH groups ).

Each of these standards though would be "Living" standards and would be
updated as need be to reflect current working practices, and so deprecation
of a document would only be a thing if the entire concept fell out of use,
and it would otherwise simply be refurbished to be current.

I would also like a space under Toolchain:: for documenting the results of
various meetings / group discussions as a collective, and those articles
would be largely write-once -> historical documents to serve as an easy
reference point to show how various policies came to be over time ( Similar
to perl5xxxdeltas )

The Toolchain:: namespace itself does not seem to be taken, and if there is
no opposition, I may start the ball rolling at some time by claiming the



Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About