1Catalyst::Contributing(U3s)er Contributed Perl DocumentatCiaotnalyst::Contributing(3)
2
6 Catalyst::Contributing - Contributing to Catalyst and Change management
7
9 How to contribute to Catalyst and what are the criteria for evaluating
10 change and deciding on the future direction of the project.
11 Change Management
13 In general there are two rules when thinking about changing Catalyst.
14 The first is technical merit of the idea. If there is a bug, then its
15 obvious it needs to be fixed. Less obvious is the types of refactoring
16 that went into giving Catalyst modern features like websocket support,
17 interoperability with event loops and to expose more and more of
18 Catalyst's PSGI underpinnings.
19 When an idea has strong technical merit, it recommends itself. The only
21 thing to consider is the needs of backward compatibility, and to offer
22 people upgrading at least some sort of path forward when features
23 change (such as to have plugins or configuration options to replace or
24 replicate something that is no longer available).
25 Then there is a second and more difficult type of change consideration,
27 which is the general will of the community. Like technical merit, this
28 needs to balance against our commitment to not leave existing users
29 high and dry with changes that break code and offer no path forward
30 that does not involve significant code rewrites. Unlike technical
31 merit, the will of the community can be hard to figure. In general we
32 don't get a lot of bug reports or conversation around Catalyst future
33 evolution. I wish I could find a way to get more involvement, but I
34 also understand this is not very unusual issue for open source
35 projects. I personally don't believe that "silence is consent" either.
36 I think choices need to have broad acceptability or the choosers lose
37 respect and authority. Typical that results in people just drifting
38 away.
39 Without direct involvement the only other way to measure the will of
41 the community is to look at what other choices people are making and
42 what other projects have received the acceptance of a broad number of
43 people. Since Plack is clearly accepted and important it leads me to
44 feel the choice to make Catalyst expose more of its Plack nature and to
45 better play with the larger Plack ecosystem are correct ones. One can
46 also pay attention to the kinds of problems that get reported on IRC,
47 at conferences and the problems that I see having looked at how
48 Catalyst has been used in the wild. For example its clear that Chaining
49 actions could use a tweak in some way since it seems to trip up people
50 a lot. The same goes with $c->forward and $c->go, which tend to lead to
51 confusing code (and combined with the stash is a particularly toxic
52 brew).
53 Going further, if we allow ourselves to look hard at projects outside
55 of Perl we can get lots of great ideas about what has worked for other
56 projects in other languages. When we see certain features and
57 approaches have excited programmers using frameworks like Ruby on
58 Rails, Django, Scala Play, etc. then it should provide us with with
59 help in thinking about how those features might influence the evolution
60 of Catalyst as well.
61 Reporting a bug
63 Reported bugs via RT or Github Issues <https://github.com/perl-
64 catalyst/catalyst-runtime/issues> that come with attached test cases
65 will be more likely addressed quickly than those that do not.
66 Proposing a bugfix patch is also always very welcome, although it is
67 recommended to stick as closely as possible to an actual bug (rather
68 than a feature change) and to not include unneeded changes in your
69 patch such as formatting corrections. In any case it is recommended
70 before spending a lot of time on a patch to discuss the issue and your
71 proposed solution, else you risk spending a lot of time on code that
72 may not get merged, which tends to be frustrating.
73 For bug patches you should create a new branch from the current master.
75 Proposing a new feature
77 You should first ask yourself if your new idea could rationally live in
78 the extended Catalyst ecosystem independently on CPAN. Ideas that have
79 demonstrated worth over time as stand alone modules are more likely to
80 be considered for core inclusion. Additionally, ideas that are best
81 achieved in core rather than as standalone, are more likely considered
82 for core inclusion than those ideas which could just as well be stand
83 alone. For example, the PSGI integration project happened because it
84 was clear that building Catalyst on top of PSGI standards would lead to
85 a better overall version than keeping it stand alone.
86 You should propose your new idea in a github issue
88 <https://github.com/perl-catalyst/catalyst-runtime/issues>, on IRC and
89 ideally on the mailing list so that other people can comment on your
90 idea and its merits prior to you writing code. If you write code
91 before proposing the idea you stand a high chance of being frustrated
92 when you idea is not accepted.
93 AUTHOR
95 John Napiorkowski jjnapiork@cpan.org <email:jjnapiork@cpan.org>
96perl v5.34.0 2021-07-22 Catalyst::Contributing(3)