1Catalyst::Contributing(U3s)er Contributed Perl DocumentatCiaotnalyst::Contributing(3)
2
3
4

Name

6       Catalyst::Contributing - Contributing to Catalyst and Change management
7

Description

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
12   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
20       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
26       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
40       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
54       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
62   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
74       For bug patches you should create a new branch from the current master.
75
76   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
87       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
94   AUTHOR
95       John Napiorkowski jjnapiork@cpan.org <email:jjnapiork@cpan.org>
96
97
98
99perl v5.36.0                      2022-07-31         Catalyst::Contributing(3)
Impressum