Name

       Catalyst::Contributing - Contributing to Catalyst and Change management

Description

       How to contribute to Catalyst and what are the criteria for evaluating change and deciding on the future
       direction of the project.

   Change Management
       In general there are two rules when thinking about changing Catalyst. The first is technical merit of the
       idea. If there is a bug, then its obvious it needs to be fixed. Less obvious is the types of refactoring
       that went into giving Catalyst modern features like websocket support, interoperability with event loops
       and to expose more and more of Catalyst's PSGI underpinnings.

       When an idea has strong technical merit, it recommends itself. The only thing to consider is the needs of
       backward compatibility, and to offer people upgrading at least some sort of path forward when features
       change (such as to have plugins or configuration options to replace or replicate something that is no
       longer available).

       Then there is a second and more difficult type of change consideration, which is the general will of the
       community. Like technical merit, this needs to balance against our commitment to not leave existing users
       high and dry with changes that break code and offer no path forward that does not involve significant
       code rewrites. Unlike technical merit, the will of the community can be hard to figure. In general we
       don't get a lot of bug reports or conversation around Catalyst future evolution. I wish I could find a
       way to get more involvement, but I also understand this is not very unusual issue for open source
       projects. I personally don't believe that "silence is consent" either. I think choices need to have broad
       acceptability or the choosers lose respect and authority. Typical that results in people just drifting
       away.

       Without direct involvement the only other way to measure the will of the community is to look at what
       other choices people are making and what other projects have received the acceptance of a broad number of
       people. Since Plack is clearly accepted and important it leads me to feel the choice to make Catalyst
       expose more of its Plack nature and to better play with the larger Plack ecosystem are correct ones. One
       can also pay attention to the kinds of problems that get reported on IRC, at conferences and the problems
       that I see having looked at how Catalyst has been used in the wild. For example its clear that Chaining
       actions could use a tweak in some way since it seems to trip up people a lot. The same goes with
       $c->forward and $c->go, which tend to lead to confusing code (and combined with the stash is a
       particularly toxic brew).

       Going further, if we allow ourselves to look hard at projects outside of Perl we can get lots of great
       ideas about what has worked for other projects in other languages. When we see certain features and
       approaches have excited programmers using frameworks like Ruby on Rails, Django, Scala Play, etc. then it
       should provide us with with help in thinking about how those features might influence the evolution of
       Catalyst as well.

   Reporting a bug
       Reported bugs via RT or Github Issues <https://github.com/perl-catalyst/catalyst-runtime/issues> that
       come with attached test cases will be more likely addressed quickly than those that do not.  Proposing a
       bugfix patch is also always very welcome, although it is recommended to stick as closely as possible to
       an actual bug (rather than a feature change) and to not include unneeded changes in your patch such as
       formatting corrections.  In any case it is recommended before spending a lot of time on a patch to
       discuss the issue and your proposed solution, else you risk spending a lot of time on code that may not
       get merged, which tends to be frustrating.

       For bug patches you should create a new branch from the current master.

   Proposing a new feature
       You should first ask yourself if your new idea could rationally live in the extended Catalyst ecosystem
       independently on CPAN.  Ideas that have demonstrated worth over time as stand alone modules are more
       likely to be considered for core inclusion.  Additionally, ideas that are best achieved in core rather
       than as standalone, are more likely considered for core inclusion than those ideas which could just as
       well be stand alone.  For example, the PSGI integration project happened because it was clear that
       building Catalyst on top of PSGI standards would lead to a better overall version than keeping it stand
       alone.

       You should propose your new idea in a github issue <https://github.com/perl-catalyst/catalyst-
       runtime/issues>, on IRC and ideally on the mailing list so that other people can comment on your idea and
       its merits prior to you writing code.  If you write code before proposing the idea you stand a high
       chance of being frustrated when you idea is not accepted.

   AUTHOR
       John Napiorkowski jjnapiork@cpan.org <email:jjnapiork@cpan.org>