On Fri, 2008-04-25 at 15:53 +0100, Matt S Trout wrote: > > There's no written standard currently; I'd love to see somebody take a > crack at writing one but I'm not sure what would need to go in it. >
I've attached a draft based on some of our company procedures to show the sorts of things that need to be addressed. I've changed a few things to reflect some of the Catalyst conventions that I am aware of but it will need your input, particular w.r.t. any conventions from PBP that you disagree with. > > having this interesting discussion. Can we put a timescale on it? What > > is the plan for release of 5.7013 and/or 5.80? > > Next week or two would be ideal; if you can't make time that soon then > you need to say -now- so somebody else can fix this. > I'd need 2-3 weeks as the next week and a half is out and I'm concerned about the time it will take to review the original code to check the subtleties, and then write new tests. The code itself is only a few minutes work... -- Jon Schutz My tech notes http://notes.jschutz.net Chief Technology Officer http://www.youramigo.com YourAmigo
(Proposed) Catalyst Coding Standards and Policies This document outlines the standards and policies for contributing to the Catalyst Project and attempts to capture the conventions that the project team has chosen to use to ensure that the quality and consistency of the code base is maintained. The project greatly benefits from the many contributors in the Catalyst community, and in turn the wider Catalyst community benefits from consistent and reliable code through adherence to these agreed standards. Any questions or clarifications regarding this document should be directed to the Catalyst mailing list. These standards are to be applied for core Catalyst development and are recommended for use with plugins and other contributed code. 1. Coding Standards 1.1. "Perl Best Practices" (Oreilly, Conway) should be followed unless otherwise noted here. 1.2. All code shall be clear of perlcritic warnings (at severity level 5), with the following exemptions: 1. Stricture disabled at line ... See page 429 of PBP. (Severity: 5) This warning is acceptable providing the 'no strict ...' is applied within the minimum scope necessary. (perlcritic does not seem to be able to reliably recognise minimum scope). 1.3 Indentation Use 4-space indentation. Hard tabs are prohibited. 2. Documentation Standards Please familiarise yourself with the Perl Best Practices description of types of documentation. 2.1 All User API functions shall have appropriate documentation suitable for end users of the API. These should appear in perldoc. 2.2 Documentation associated with functions and methods that are not part of the User API shall be as follows: - private functions and methods (as identified by a leading underscore in the function/method name) shall have any documentation in comments so as to not appear in perldoc. - internal functions and methods (meant for use within the same package only) shall be flagged as such and have documentation in comments so as to not appear in perldoc. - internal functions and methods that are not for general users buy may be used by extensions (which may be packaged separately, such as derived classes or plugins) should appear in perldoc, clearly identified as "Developer API" methods. 3. Testing Guidelines Write the documentation for your API functions to adequately define the inputs and expected outputs. Then write tests that match. * Each module should have at least one corresponding file in the 't/' test directory. Permissible exceptions: o where the module is trivial, such that it can be adequately tested by code inspection o where the module requires external infrastructure (e.g. a remote website) which is unreasonable to duplicate; in this case it may be more appropriate to add a working example into the 'examples/' subdirectory. Make sure that everything that can be reasonably tested through a regression test, is; this might mean splitting the module, placing the reusable, testable components in their own modules and keeping the application level code that requires the external infrastructure separate. o modules which only include configuration data for a suitably tested parent class may not need their own tests * All public methods (user and developer API methods) should be tested. Permissible exceptions: o where the method is inherited and suitably tested in the parent class o where the method is created through configuration of a suitably tested parent (such as accessors created using Class::Data::Inheritable or Class::Accessor) * Testing of private/protected methods may be appropriate when sufficient test coverage is difficult to achieve when testing through the public methods. Due to the possible maintenance issues that this might cause, it should be used sparingly. * Do a test coverage analysis using Devel::Cover. Target test coverage as reported by Devel::Cover should be >80% for each module. Devel::Cover invocation: cover -delete HARNESS_PERL_SWITCHES=-MDevel::Cover make test cover 4. Contributing patches 4.1 Patches should be against the current CVS head revision. 4.2 Ensure your patches are accompanied by tests and appropriate documentation as described above. 4.3 Submit your patch to the Catalyst mailing list for public review, and from where the maintainer responsible can take the patch and apply it. Include a description of the problem, a failing test case (pre-patch), and a description of how your patch overcomes the problem. 4.4 When providing patches to any module, please review the module in the context of the standards and policies on this page, and upgrade if necessary. 5. Review and Release Guidelines 5.1 Backward Compatibility 5.2 Point Releases and Major Releases 5.3 Review Procedure 5.4 Release Procedure 5.5 Who's responsible REFERENCES Perl Best Practices, Damien Conway, http://www.oreilly.com/catalog/perlbp/toc.html Catalyst::Manual::DevelopmentProcess Catalyst::Manual::ExtendingCatalyst
_______________________________________________ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/