Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD
On 7 May 2015 at 23:37, Philippe Bruhat (BooK) 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
Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD
On Thu, May 07, 2015 at 08:33:00AM -0700, John SJ Anderson wrote: > > This may be a good time to point out my Jekyll-ish static site publishing > framework HiD (https://metacpan.org/release/HiD) has an option to publish > direct to GitHub pages. cpan.io is its own webapp, turned into a static website via my own Wallflower (https://metacpan.org/pod/wallflower). Of course, everyone has to build his own! ;-) -- Philippe Bruhat (BooK) None suffer so much in a war as those who strive to end it. (Moral from Groo The Wanderer #51 (Epic))
Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD
On Thu, May 7, 2015 at 12:30 AM, Philippe Bruhat (BooK) < philippe.bru...@free.fr> wrote: > On Thu, May 07, 2015 at 06:14:57PM +1200, Kent Fredric wrote: > > > > Even some git based workflow that published to github pages with some > > atrocity of jekyll would be better for this task IMHO than a wiki. ( This > > is also a "moderately low barrier to get it working using existing > > contribution systems" thing ) > > Hey, this is exactly what I was proposing in my other email: aggregating > documents that live on specific branches of specific directories. > > I'll try to quickly produce a proof-of-concept. This may be a good time to point out my Jekyll-ish static site publishing framework HiD (https://metacpan.org/release/HiD) has an option to publish direct to GitHub pages. It currently doesn't support POD as an input format (only Markdown and Textile) but I don't think that would be that hard to add; that layer is pluggable. chrs, john.
Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD
On Thu, May 07, 2015 at 01:37:55PM +0200, Philippe Bruhat (BooK) wrote: > > The current reference documents are obtained from these repositories: > - https://github.com/neilbowers/history-of-cpan.git > > Unless someone objects, I'll put this live in a day or two. > Because it's much simpler to see what it looks like without having to build your local cpan.io, I've put the code live with only Neil's history of CPAN, which cpan.io was already publishing. http://cpan.io/ref/cpan/history.html The benefit is that now we're back to having a single authoritative source for that document. I've sent Neil a pull request with the patches I received for my version of the document. The only remaining commit on the book/publishing branch is the one that enables publishing the content of the toolchain-site repository. I'll only apply that if David agrees. -- Philippe Bruhat (BooK) When you wander near evil, Security is only a function of foolishness... (Moral from Groo The Wanderer #21 (Epic))
Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD
On Thu, May 07, 2015 at 09:30:59AM +0200, Philippe Bruhat (BooK) wrote: > On Thu, May 07, 2015 at 06:14:57PM +1200, Kent Fredric wrote: > > > > Even some git based workflow that published to github pages with some > > atrocity of jekyll would be better for this task IMHO than a wiki. ( This > > is also a "moderately low barrier to get it working using existing > > contribution systems" thing ) > > Hey, this is exactly what I was proposing in my other email: aggregating > documents that live on specific branches of specific directories. > > I'll try to quickly produce a proof-of-concept. 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. -- Philippe Bruhat (BooK) Beauty may be a curse, but not as great a curse as stupidity. (Moral from Groo The Wanderer #11 (Epic))
Re: File::ShareDir - Outstanding modernization
Hi all, I re-ordered the quotes to avoid sending multiple replies but answer in order. > 2015-05-04 16:34 GMT+02:00 Jens Rehsack : > Hi, > > initially planned being one big topic for my QAH attendance, but Murphy > decided to keep me busy otherwise (broken car, for everyone who didn't > recognize on QAH...). > > Well - things are settling meanwhile and I have a few moments to think > about the tasks I missed to finish in Berlin. One is File::ShareDir. > > The intension is to let File::ShareDir get closer to File::ConfigDir > (and later let File::ConfigDir steal some features from File::ShareDir). > > The longterm goal is having it behave a bit more like "share" is intended > (read until end of mail - don't scream here). There is no plan to break > backwards compatibility (and if it happens on accident, the intension is > to fix it and hopefully detect before it happens). > > Back to ideas for File::ShareDir: > > 1) analogous to File::ConfigDir have a bunch of share-dir prefixes >including existing prefixes (core_share_dir, site_share_dir, >vendor_share_dir, ...) and new ones (system_share_dir, machine_share_dir, >here_share_dir, ...). >==> here is can be sane to have plugins like > https://metacpan.org/release/File-ConfigDir-Plack >for $ENV based locations (eg. FOO_BASE) or framework related extension. > 2) Upon the prefixes, the dist_dir(), module_dir() will calculate the >Full Qualified Share Dir as requested. It'll very likely to have other >preferences is prefix picking for legacy API and new API (-> 3) > 3) introduce better accessors (dist_share_dir, module_share_dir, > app_share_dir, >dist_config_dir, module_config_dir, ...). > > The goal is allow a module access share-dirs from different applications > (eg. templates to process) or let applications rely on different immutable > files from several distributions (think LaTeX as an example). > > On Tue, May 5, 2015 at 6:14 AM, Olivier Mengué > wrote: > Hi, > > Is it really necessary to introduce those new features (bloat?) in the > existing File::ShareDir ? I think so. Reason follows ... > Why not just fork and keep the original File::ShareDir light? > What problems would be solved if the new features you plan were added to the > existing File::ShareDir? Which existing application would benefit from these > change just by upgrading to that new File::ShareDir, without using the new > APIs? The original File::ShareDir isn't that light. The reason for reworking File::ShareDir is the missing support for a real share concept which confuses more end-users. Many (but not even close to all) Experienced developers understand the pitfalls and manage to deal with that. So introducing the support as intended is from my point of view necessary, while supporting existing API. That's not bloated. > On Tue, May 5, 2015 at 2:35 PM Karen Etheridge wrote: > I am not opposed in principle to redesigning File::ShareDir, but I want to be > *very* clear about the proposed design changes, impact on various parts of > the toolchain, and back-compatibility concerns before anything moves beyond > the design phase. This is the intension of this thread. First discussing design details - on a probably very abstract level. Depending on the discussion we might need a more details design discussion or we can directly move to code (in a branch!). > This code sits at the very heart of the cpan, called directly by > ExtUtils::MakeMaker. You're not talking about https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker/pull/21, do you? > Am 06.05.2015 um 02:33 schrieb breno : > > Hi Jens! > > I'd love to have a module providing an improved and modern interface to > File::ShareDir and I think the entire community would greatly benefit from it > - not just the toolchain. That said, I would rather see it in a new module > than have it in File::ShareDir itself. Kinda like how nowadays I prefer > Path::Tiny over File::Spec + Cwd (or even Path::Class). We can talk about a simplified interface on top of such low-level classes. Maybe it is a sane proposal to avoid to much new public API but accessors for a module on top of this. Can you imagine creating a proposal for such a high-level module which maybe covers ShareDir and ConfigDir for eg. an CLI application like App::Math::Tutor and a Web-Application using templates (not design!) in share and a configuration in etc/ telling where the web-root is, the share-name (referring to my "app_dir" proposal). Cheers -- Jens Rehsack - rehs...@gmail.com
Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD
On Thu, May 07, 2015 at 06:14:57PM +1200, Kent Fredric wrote: > > Even some git based workflow that published to github pages with some > atrocity of jekyll would be better for this task IMHO than a wiki. ( This > is also a "moderately low barrier to get it working using existing > contribution systems" thing ) Hey, this is exactly what I was proposing in my other email: aggregating documents that live on specific branches of specific directories. I'll try to quickly produce a proof-of-concept. -- Philippe Bruhat (BooK) When you create a climate of peace, you have only fair weather. But where the climate is one of violence, it can only rain blood. (Moral from Groo The Wanderer #120 (Epic))
