plainblack.com
Username Password
search
Bookmark and Share

    
Goto page «Previous Page   1 2 3    Next Page»

The policy for contributions to the WebGUI core

User arjan
Date 4/12/2008 8:35 am
Views 27562
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:
        <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



Back to Top
Rate [
|
]
 
 
colink

I'm still reading and digesting this.  It's the most complete list of dev requirements that I've seen to date, so thank you for your hard, exhaustive work.  All of us devs, and future devs, will benefit from this.

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.

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



Back to Top
Rate [
|
]
 
 
arjan

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



Back to Top
Rate [
|
]
 
 
JT

In general yes I'd say that this is the complete list as it stands now. Of course like any living document it's open both to interpretation and amendment. 

Ultimately the final word on what does or doesn't get into WebGUI resides with me. And here are the more subjective things that I weigh in that consideration:

  1. What percentage of the current or future WebGUI world will likely find this feature useful? Anything less than 30% and I have to have some other reason to include it. Anything less than 10% and it likely won't get included, unless it can be switched off, or easily removed so it is out of the way of your average user.
  2. Is this feature usable by our target audience with their current skill set? The target audience: normal business users (that is unless it has it's own audience, like userImport.pl clearly targets sys admins). 
  3. 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)?
  4. 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. Therefore the maintenance cost is important for us to consider.
  5. Does this feature fit the direction I want WebGUI to go? For example, we've always focussed on business users, and perhaps someone wants to do a heavy integration with MySpace or some other consumer level service. A consumer audience is not something I'm really interested in pursuing unless it has some advantage to our target audience, business users.
  6. Is there a similar feature in WebGUI that could be adapted for the purpose this new feature wants to fit?



Back to Top
Rate [
|
]
 
 
koen

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



Back to Top
Rate [
|
]
 
 
JT
That's roughly it. But more specifically not money for implementing it, but rather increased sales for having it be a standard feature. You can call it a competitive advantage. 

JT
On Apr 12, 2008, at 4:26 PM, <koen@procolix.com> wrote:

koen wrote:

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



http://www.plainblack.com/webgui/dev/discuss/the-policy-for-contributions-to-the-webgui-core/3


--

Plain Black&#44; makers of WebGUI
http://plainblack.com


Back to Top
Rate [
|
]
 
 
koen

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



Back to Top
Rate [
|
]
 
 
JT

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. 

How would such a part be defined?

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

I have a pie in the sky idea for Lift (the upgrade system we talked about) where we'll set up a repository so that WebGUI developers other than Plain Black can publish their WebGUI plugins (assets, macros, whatever) and then site owners, through a GUI interface can install/upgrade those plugins remotely. I think that's a much better long term approach than keeping everything in the core. That way you truly do own, document, support, and bug fix your own features.

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

I don't want to stir up any bad blood on features that have not gone so well, so I'll talk about one of the exceptions that has worked well. Much of the stuff Martin Kamerbeek has written for WebGUI, whether for his work at ProcoliX and Oqapi or on his own, he's been very good about helping out with both in bug fixing and answering people's questions on the forums and IRC. Many others though have contributed chunks of code and then we never hear from them again. It's nice to get the code, but it's even nicer to get help from those people after the code is in. That's part of the reason why I'm being so strict these days about code quality, POD, tests and whatnot. If PB is going to have to support it, then we want it well documented and tested to make it easier to support.



Back to Top
Rate [
|
]
 
 
koen

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



Back to Top
Rate [
|
]
 
 
koen

How would such a part be defined?

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

I have a pie in the sky idea for Lift (the upgrade system we talked about) where we'll set up a repository so that WebGUI developers other than Plain Black can publish their WebGUI plugins (assets, macros, whatever) and then site owners, through a GUI interface can install/upgrade those plugins remotely. I think that's a much better long term approach than keeping everything in the core. That way you truly do own, document, support, and bug fix your own features.

I like this idea very much. Could this be noted as a long term objective?

I also agree absolutely that making WebGUI even more pluggable then it already is is the best approach for the long term.

How can we (the not Plain Black companies) help in the best possible way to achieve this goal?

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



Back to Top
Rate [
|
]
 
 
     Goto page «Previous Page   1 2 3    Next Page»



© 2020 Plain Black Corporation | All Rights Reserved