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:
        <IfModule mod_headers.c>
         <FilesMatch "\.(pdf|ppt|doc)$">
             Header append Content-Disposition "attachment;"
         </FilesMatch>
        </IfModule>)

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.

P.S. I send this earlier not via the site but via email and it seems not to be received. (02:29 Amsterdam time)

Kind regards,

Arjan Widlak

United Knowledge
Internet for the public sector

www.unitedknowledge.nl

Point #5 I think is a little too broad in its wording.  Not all www_ functions are templatable.  Take www_edit, for example.  I think it's safe to say that all "user" www_ functions should be templatable, where "user" means not a content manager or admin.

Yes, clear.

Point #7.1 is a goal.  WebGUI itself does not completely pass the Gentle level of PerlCritic, last time I checked it in January.

Yes, but I would guess that since this a goal, for new code this a requirement.

Kind regards,

Arjan Widlak

United Knowledge
Internet for the public sector

www.unitedknowledge.nl

Is there a monetary incentive to include it in the core, for Plain Black or any WebGUI integrator (United Knowledge being one of those integrators)?

I'm not sure what you mean here. Do I get it if I rephrase it this way?

Does Plain Black or United Knowledge or any other company that earns it's money by supporting WebGUI get better financially by adding this feature to the core?

Koen de Jonge - ProcoliX
http://www.procolix.com
Hosting - WebGUI - Virtualization

What is the maintenance cost of this feature? This is important because once it's in the core it's primarily Plain Black's responsibility to support, document, and fix bugs for it. It would be nice to think that other people in the community would step up to do it, but with a few exceptions, this hasn't been the case historically.

This is interesting. I think the stance on this could do with a little extra attention, since changing the tides on this point would make a lot more possible.

JT, do you see a way to get a breaktrhough on this issue. Could for example ProcoliX be made responsible for a part of the core to support, document, and fix bugs for it?

How would such a part be defined?

Is it actually possible to give this kind of responsibility out of the hands of Plain Black?

Could you give an example of an exception from the history and elaborate on what went well and what went not so well?

Koen de Jonge - ProcoliX
http://www.procolix.com
Hosting - WebGUI - Virtualization

JT, do you see a way to get a breaktrhough on this issue. Could for example ProcoliX be made responsible for a part of the core to support, document, and fix bugs for it?

How could that be possible? You're going to man our support boards and phone lines to answer questions about a single feature in WebGUI? Certainly fixing bugs could be assigned to you, and maybe the documentation as far as it goes in the Wiki, but not for our books, and not for our support center. 

I was wondering if you would see a way in which it could be achieved. I think I have to agree that it would be at least nearly impossible.

I agree that you probably wouldn't want other people than Plain Black staff to man your support boards and phone lines, other then by contracting them. You would have to have some form of control over them if only it where for quality assurance.

The best way I can see is that more parts will be pluggable and the core would be as lean as possible. See my other replies to this same post for clarity reasons.

Koen de Jonge - ProcoliX
http://www.procolix.com
Hosting - WebGUI - Virtualization