- Name:
-
John Napiorkowski <jjnapiork@cpan.org>,<jjn1056@gmail.com>
- Amount Requested:
-
TDB
'Perl Catalyst Web Framework for Heretics', A.K.A 'Catalyst, the Good Parts', is a contemporary tutorial for Perl Catalyst, the cornerstone Modern Perl web applications framework. This tutorial will be a blend of step by step assembly of a basic but non trivial application with my best practice insights which I have gleamed from over 10 years of on the job use of Catalyst.
The core application developed will be a a multi user 'Todo List' application. This will include user registration as well as authentication and authorization examples. Websites such as http://todomvc.com and http://todobackend.com have demonstrated that many people find the basic and enhanced 'Todo List' a sufficiently complex application as to well explore the flavor of a web application framework without being so complicated as to impede learning.
Technologies covered in the tutorial will include Catalyst, DBIx::Class, Data::MuForm, Template::Lace as well as supporting modules in the expanded Catalyst ecosystem (such as Catalyst::Plugin::Authentication).
Best practice discussion will include reviewing and questioning many common Catalyst development practices in the light of what worked and what failed in the wild, according to my experiences. This will include a discussion of which parts of the Catalyst API in retrospect are not ideal, and how to avoid them or work around them (this is the 'for Heretics / Good Parts' aspect of the tutorial).
As part of the exploratory work I have done to investigate the possibility and effort level of this project, I have created a basic prototype of the Todo application and placed it on github https://github.com/jjn1056/TodoMVC.
Although Catalyst is a cornerstone project in the Modern Perl era, one that has broad use in many companies worldwide, its documentation has long suffered from neglect due to insufficient time by those with the technical ability to write it. Often it has been a choice between time fixing code and time writing better docs. Previously I have tried to ease this problem by using the yearly Advent cycle as an opportunity to cover "What's New and Improved" but this is not the type of systematic tutorial level documentation that I often hear requested. Whenever I ask people "what do we need to improve about Catalyst"? documentation is nearly always mentioned as a top wish.
In the past I've attempted to kick off documentation update projects for Catalyst but never got a lot of traction. I believe this is so because most of us are very busy on the job and can barely make time to 'scratch our own itches' with technical patches. This makes documentation purely a pro bono voluntary affair, which has lead to inconsistent and out of date documentation. I believe a grant for this work will lead to a better result than previous pure volunteer efforts. Benefits will included helping those that are new to the framework (and hopefully help make Perl itself a more attractive choice to people and companies making strategic bets on what technology to use) as well as to people that have been using Catalyst for a number of years and often wondered if they are following best practices for building a sustainable and maintainable application.
My greater hope is that having a new tutorial with contemporary ideas will generate interest and conversation in the Catalyst community itself, and help to lead to a new wave of excitement about the framework and developers willing to help make it a framework that is viable into the next decade and more.
The tutorial will be a series of POD documents checked into a Github repository (under the Catalyst organization). There will be one POD document per chapter as documented under "Project Details". Since the project will be run in the open I will be continually seeking community review; furthermore when I have completed all chapters I will invite the community to assist in a final review (period described under "Project Schedule"). I will be making regular announcements about project status via the Catalyst mailing list, on the support IRC channel and via my blog (no less then one announcement per chapter).
In additional all code for the tutorial will also be checked into Github. The git history will be tagged such that it shall be easy for someone to get at the state of the application for each chapter. That way a person can review the independent steps leading to a complete application as they follow the tutorial.
All work will be licensed under the Perl Artist. To be specific, all files checked into the repository will contain the following line:
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.It is my intention to assign copyright to the community as well, however I would appreciate the grant committee's advice on the correct wording for this.
A good example of the level of documentation I will seek to deliver (as well as a good example of my style and ability to succeed in the job) can be found in my tutorial for another open source project I founded DBIx::Class::Migration. See https://metacpan.org/pod/distribution/DBIx-Class-Migration/lib/DBIx/Class/Migration/Tutorial.pod for direct link to that tutorial.
As mentioned in the "Synopsis" as part of my preparation for applying for this grant I prototyped a basic version of the Todo application, which is on Github at https://github.com/jjn1056/TodoMVC.
What I mean by 'Catalyst for Heretics' is that my tutorial will contain some novel suggestions and alternative practices to those which have been cargo culted since 2006. These alternative practices are my response to what I see as the most common problems or architectural design mistakes I've seen in Catalyst applications in the wild, on the job. Not all these ideas may be perfect ones, but they will be working solutions designed to provoke deeper thought about what Catalyst users could do differently to design better and more maintainable applications, as well as take better advantage of the features that Catalyst brings to the table.
Another possible title for this tutorial could be, "Catalyst: The Good Parts", since it is my intention to identify some of the worst warts in the framework and in common practice that are best avoided. However it seems that type of title is under trademark :)
As previously mentioned there is a basic, working prototype for the Todo application on Github at https://github.com/jjn1056/TodoMVC, although the application we develop in the tutorial will eventually be more sophisticated. It can be reviewed to get a sense of what I mean by "Catalyst for Heretics".
Development of the tutorial will follow a hybrid agile style. Each chapter will begin with one or more agile use cases the document will seek to solve. For example:
As a Catalyst programmer I want to understand basic design patterns that
Catalyst uses in order to use them properly and design better, more
maintainable code.As side benefit of following the agile model is that each chapter will provide a meaningful and complete deliverable. That way if for some reason I cannot complete the project, the completed work to that date will be useful in and of itself. This way we reduce risk in funding the project since any amount of completion will add some value for the community.
Additionally a chapter may list specific Catalyst patterns to use (as well as anti-patterns to avoid).
Out of Scope:
I presume Perl knowledge and general knowledge of Modern Perl practices. As a result I will not go into details around installing Perl, setting up a local::lib, etc. Links to details will be provided for those learning.
Other technologies used in the tutorial, such as DBIx::Class will be covered in an 'as needed to understand the chapter' basis (it will not be an extensive DBIC tutorial and I will presuppose working knowledge of the ORM framework, or a willingness to follow links to such documentation as already exists).
I will also only sparingly cover topics in authoring CSS and Javascript as this tutorial is aimed at Catalyst development best practices, not general web development best practices. It is possible that a followup grant focused on transforming the target application into a Javascript enhanced or single page application may be submitted based on community interest.
Since security is a big topic I will only cover it sparingly; mostly I will try to be point out possible security issues but will in this tutorial not cover it in sufficient detail to be complete. I'd rather leave it unsaid rather than incorrect.
Lastly issues of internationalization / localization and accessibly will not be considered in scope (again these are big topics that could form the basis of future grants to extend the documentation).
Sprint 0 (Project Kickoff): Setup of repository and basic project management tasks, announcement of project start (Blog, IRC, Mailing List, etc).
Sprint 1: Introduction: Why Perl Catalyst?
"As a programmer I want to fully understand the value and features
of Perl Catalyst so that I can make an informed decision on using it."
"As a programmer I want to learn about what use cases Perl Catalyst is
good at solving so that I can make sure it is the correct framework for
my project".
"As a programmer I want a list of further reading resources about Catalyst
so that I can continue to explore the framework in greater detail."Sprint 2: Classic "GoF" Design Patterns
"As a programmer I want to understand how classic design patterns such
as Model View Controller are implemented in Catalyst so that I can use
them properly to build well organized and maintainable code."Sprint 3: General Best Practices.
"As a programmer I want to know about how to use general design best
practices within the Catalyst framework so that my application is well
designed, easy to understand and can scale in complexity as my business
rules change."
"As a programmer I would like to learn about common Catalyst anti-patterns
so that I can avoid them in my code."Sprint 4: Initiating a new Project.
"As a programmer I need to setup a basic working environment where I
can development my new Catalyst application."
"As a programmer I need a basic Catalyst project skeleton so that I
can begin the work customizing it to meet my project needs."
"As a programmer I want to build a basic "Hello World" application so
that I can see that my environment is working properly."Sprint 5: Views and Static Content.
"As a programmer I need a View to display a list of my Todo Items."
"As a programmer I need Views to cover global issues such as displaying
error messages and when a URL is not found."
"As a programmer I need a way to display static content such as CSS."Sprint 6: DBIx::Class and the first Todo List Model
"As a programmer I want an example of adding a relational database to
my infrastructure so that I can use a database for my application."
"As a programmer I want to see a standard setup for using DBIx::Class
so that I follow DBIC best practices."
"As a programmer I want an to see an example Todo model built using
DBIx::Class so that I can learn the system better."
"As a programmer user I want some guidance on migrations and deployments
so that I properly version and manage change at the database level."
"As a programmer user I want some guidance on creating test cases so
that my code is quality assured."Sprint 7: Integrating DBIx::Class into Catalyst
"As a programmer I want guidance on integrating my DBIx::Class Todo
model into my Catalyst application so that Catalyst can interact with
a database."
"As a programmer I want to display seed data Todo items in the web browser
so I can verify my DBIx::Class integration is working".
"As a programmer I need guidance on writing test cases against my Catalyst
application."Sprint 8: CRUD (Create, Read, Update, Delete) and Form Validation
"As a todo list user, I need the ability to create new todo items as well
as edit and delete existing items."
"As a todo list user, I need to make sure my todo titles meet certain
criteria such as minimum lengths and are unique."
"As a todo list user, I need views that let me edit a todo item and add
one as well as display any validation errors."Sprint 9: Expanding the Model and Views
"As a todo list user, I need to be able to add notes and deadlines to
my tasks so that I can better understand them and prioritize them."
"As a todo list user I need my list organized into 'pages' so that I
can better manage a long list."Sprint 10: Authentication and Login (Single User)
"As a todo list user I want to protect my tasks with a login page."
"As a programmer I need a view and form for the new login page."
"As a programmer I need a view and form for the new user profile page."Sprint 11: Multi User Todo Manager
"As a user I would like to register for an account on the Todo Manager
so that I can use the application".
"As a programmer I need a view and form for the new registration page."
"As a programmer I need a view and form for the new password recovery page."Sprint 12 (Project Finalization): Final code checkin of all responses to critique, announcement of project completion (including mail list announcements). Update existing Catalyst website to link to the new tutorial. Add link in the IRC help channel topic as well as links in the CPAN published version of Catalyst
I anticipate dividing time so that the main work of a new chapter takes place over the course of two weeks, with a week public review and any corrections or updates to take place the following week, along with time spend managing announcements of the project status. So the basic breakdown of a two week work cycle is is:
1) Finalize chapter based on review and comments from previous week.
2) Start and complete draft version of next chapter.
3) Announce current status via blog and other communication channels.At the end of each work cycle (or sprint) I will re-evaluate the project standing and determining if I'm still on course toward completion or if anything needs to be changed in order to reach success.
There will be a one week period for final overall review and publication as well as an initial kickoff week. During those two weeks I will not be writing tutorial code, instead spending my time on project management, communications and publication. Based on this I expect the project to last no more than 26 weeks. I anticipate starting the project no later than 30 days after the grant has been accepted.
I would consider the project to be complete when all chapters have been written and checked into Github, along with all the application source code, under the Catalyst organization, and all the announcement tasks mentioned have been completed.
My name is John Napiorkowski. I've been programming in Perl since the mid 1990s and have extensive experience with Catalyst since the beginning of 2006 (my first commit to the project was on 28 April 2006; you can see the commit in Github here: https://github.com/perl-catalyst/catalyst-runtime/commit/5e7073968974a588522d61b3a72b23cd87a8121a (I believe I emailed mst a tar-ball, which is why the commit is under his account)).
As an open source commuter on the project I have made many contributions including my work to help complete the Cata-Moose (Catalyst Moose conversation) as well as the Cata-Plack (Catalyst to PSGI conversion) projects. From 2013 to 2015 I was the primary release manager and to date have published more than 80 stable and development releases of Catalyst to CPAN. Additional highlights of my technical contributions would include the work I have done to improve support for UTF-8 and other character sets, streaming response support and experimental support for advanced protocols such as Web-sockets. I have also taken on updates and improvements to the existing API level documentation.
I have also contributed heavily to Catalyst CPAN ecosystem projects (a full list of my contributions to Catalyst CPAN ecosystem as well as my CPAN contributions in general can be found here: https://metacpan.org/author/JJNAPIORK
Beyond my technical contributions I have blogged about Catalyst for several years and for three years managed and authored many articles on Catalyst for the 2012 thru 2014 Advent season (see http://www.catalystframework.org/calendar/). Additionally I am a regular presence on the #catalyst IRC channel and presented on Catalyst topics at YAPC:EU in 2016.
Professionally I have used Catalyst at 5 different companies and have a deep understanding of what has gone well and poorly with Catalyst practices on the job For more general information about myself and my open source / professional work the following links may be of value:
https://metacpan.org/author/JJNAPIORK, https://github.com/jjn1056, https://www.linkedin.com/in/jnapiorkowski/
Citizenship / Residency: I am a citizen of the United States and expect to reside in the U.S.A for the duration of the grant.
Might I suggest adding an official Docker image so people can quickly get started.