plainblack.com
Username Password
search
Bookmark and Share

    

The policy for contributions to the WebGUI core

User arjan
Date 4/12/2008 2:05 pm
Views 1587
Rating 1    Rate [
|
]
Previous · Next
User Message
arjan
Dear all,

Everyone can make contributions to WebGUI. It's easy, it's described in
the wiki:
http://www.webgui.org/community-wiki/getting-started-in-the-webgui-community
But how to get something into the WebGUI core?

This wiki page
http://www.webgui.org/community-wiki/how-to-add-a-feature-to-webgui-core
says there are three ways:
1. A strategic decision is made by Plain Black to implement certain
functionality into a feature release.
2. A customer chooses to fund the development of a core feature that
will benefit WebGUI.
3. Request For Enhancement (RFE) is submitted. (and of course you could
attach a patch at the same time)

There are readers on this list that know there is a forth way:
to discuss the feature on this dev-list and ask for permission to build
and commit it yourself into WebGUI.

In a best case scenario this is what happens:
1. the collective intelligence of this community brings the idea to a
higher level: more general, more elegant, more flexible and powerful
than the original idea
2. many people get inspired in this process and offer you their help
3. you ask our project leader for permission
4. he reminds you of
http://www.webgui.org/community-wiki/development-best-practices and
5. since you are a known member of the community, gives you the
go-ahead.

Point 4) the Development Best Practices (DBP) is what I would like to
discuss. It's the policy of the community. It's mostly implicit, just
like the constitution in many countries. It seems so obvious, there's no
need to write it down. Everybody knows, right? Let's try this.

These are things that we all agree should be part of the WebGUI DBP:
1. All testable functions should have tests
http://www.webgui.org/community-wiki/developers-guide-to-testing-in-webgui
Since it's hard to test www_ functions, they don't need to have tests,
but all others should.

2. Every module and function should have POD documentation
http://www.webgui.org/community-wiki/plain-old-documentation-pod
Describe how to use the functions and what parameters can be passed to
the function.

3. The module should be internationalised
http://www.webgui.org/community-wiki/internationalization
All messages to the user should be retrieved from an i18n language
package.

4. All template variables should be documented in a help module
http://www.webgui.org/community-wiki/the-help-system

5. All www_ and email views should have selectable templates
Apart from the Operation/Profile/View, the Operation/Profile/Edit and
the Send Invitation Template almost all templates are selectable. And
almost all views are templatable.

6. If you use javascript, use the YUI library
The Yahoo User Interface Library YUI (http://developer.yahoo.com/yui/)
is what you could call a javascript or AJAX library. Of course you
always have to script some things together, but use as many reusable
parts as possible.

7. Make sure you deliver quality code so:
http://www.webgui.org/community-wiki/development-best-practices
7.1 Use the Perl Best Practices so that you at least pass PerlCritic on
gentle level
The PERL Best Practices help you to write readable and maintainable code
and since your contribution goes into a community project, others should
be able to read and maintain it to. (But do not use "return;" as
described in the PBP and use 115 characters per line.)
7.2 Reuse code
Use the WebGUI API and the modules on CPAN as much as possible.
7.3 Stay database agnostic
7.4 Put a horizontal separator above each "sub" statement
7.5 Keep your methods and subroutines in alphabetical order
7.6 Always mark private methods with an underscore
7.7 Always mark methods that are accessible to the web with www_
7.8 Never abbreviate anything
7.9 Refrain from using the default variable ($_)
7.10 Use object-oriented design where it fits and procedurel where it
fits
7.11 Balance method granularity with code readablity
7.12 For every plug-in you create select a new namespace

8. Never use a dot (.) in template names, but use underscores

9. Default templates and other HTML your the code produces has to be
accessible wich means:
9.1 XHTML 1.0 strict compatible
9.2 CSS 2 or 3 compatible
9.3 WCAG Priority 1 compatible
9.4 Section 508 (US) =~ Webrichtlijnen (NL) compatible
9.5 Do not use target="_blank" to open new windows and do not use
javascript unless there is an alternative to access the content. (A
consequence of accessability rules.)
9.6 Links to files should offer the option to save them or to open them.
(Also a consequence of accessability rules and this could be reached by
adding something like this to all modproxy templates:
    
       
            Header append Content-Disposition "attachment;"
       
       )

I think we all agree on these points, but let's see. I know 7.10 and
7.11 are open for interpretation, but that's why we have a dev_list and
a judge/project leader. But in general: are these are demands, to
contributions to the core? And is this list complete? Are these *the*
demands to contributions in the core?

Besides these requirements, that contributions have to meet, of course
there has to be consensus about the desirability of the feature. This is
highly subjective, so here we will need the judge the most. But this is
what the dev_list is for as well.

So to come back to my two questions:
a) do we agree on these 9 demands?
b) is our policy list 9 articles long or longer?

P.S. I'm away for the weekend, so don't expect me to reply before
monday.

Kind regards,
Arjan Widlak

United Knowledge
http://www.unitedknowledge.nl/




Back to Top
Rate [
|
]
 
 
    



© 2020 Plain Black Corporation | All Rights Reserved