Developers of Sympa

[Guillaume Rousse <address@concealed>]

Le 19/12/2012 11:07, David Verdin a écrit :
[..]
> > * Packages export cleanup
> > No package export anything anymore, and all usage of external
> > subroutines/variables always use fully-qualified name.
> I'm a little fuzzy on this: Does it mean that, to access data in a
> module, we need to use accessor subs (get_something, instead of
> Module::something) ?
You're confusing with encapsulation here.

Encapsulation means preventing direct access at private data, so as 
limit access to a public interface. Hence the preference for 
$objet->get_foo(), instead of $object->{foo}. However, they are few 
tchnicals solutions to achieve this in perl, and generally, it is 
achieved through conventions: if something is labeled as private (the 
usual way being to prefix it with underspace), it should not be used 
outside its own namespace. That's also why private subroutines are not 
documented in POD format.

What I'm talking about here is the usage of symbols declared in another 
package from yours, without refering to it with its fully-qualified 
name. When you load the POSIX module at compilation time, through 'use 
POSIX' statement, you can access its strftime function either as:
POSIX::strftime()

or as
strftime()

because it was automatically imported in caller namespace. If however, 
you loaded the POSIX module at runtime, through 'require POSIX' 
statement, or with an explicitely import list, though 'use POSIX qw()', 
you can only access it through its fully-qualified name only:
POSIX::strftime()

This import mechanism is controlled both ways:
- the provider package declares what it allows to be exported
- the caller package declares what it actually import

As the general convention in sympa's code was to always use 
fully-qualified form (which also makes easier to understand exact code 
location), exporting symbols was just useless noise.

[..]
> > * Generalisation of strictures usage
> > All packages now use strict.
> No kidding? Did you also achieve the impossible, i.e. using strict in
> wwsympa.fcgi? ;-)
I'm even targetting taint mode in the long term :)
Sofar, that's just for perl modules, not executables.

> > * Interdependencies cleanup
> > The large tools package have been splitted in multiple ones:
> > Sympa::Tools::File, Sympa::Tools::Time, etc... This allow to leverage
> > dependencies issues, including circular ones.
> >
> > Many subroutines requiring direct access to Sympa::Configuration have
> > also been modified to receive required values as parameters, allowing
> > to break more circular dependencies. This also make them more modular,
> > and easier to tests.
> Indeed.
> We inscreasingly use objects, which most of the time carry their own
> parameters, making method calls easier - most of the time, the fucntions
> I create don't use parameters at all). So parameters will probably be
> used only for utility modules sucha as mail.pm, and the offspring of
> late tools.pm. So the increased attention required to call functions
> using parameters instead of config will remain restricted to few areas
> of the code.
Using either OO or procedural interface doesn't really change the issue 
here: if an object constructor uses values from Sympa::Constants or from 
a top-level Sympa::Configuration object at instanciation time, it still 
has an hard dependency for those packages.

For instance, see Sympa::Lock class constructor, which relies on 
Sympa::Constants::USER and Sympa::Constants::GROUP. You can't create a 
lock object with arbitrary user and group, for testing purposes, 
notably. If you use parameters in the method call instead, you're 
pushing the dependency in the caller, and you're making Sympa::Lock more 
flexible.

In this specific case, tough, a better solution would be to drop the 
useless call to set_perms() requiring those values, as any lock file 
created through open() call will already belong to the sympa user and 
group :)

> > As a result, all packages can now be loaded separatly...
> Great! It will be so easier now to use them.
> We'll need to be carefull when adding new code, now, to prevent creating
> new interdependencies. Maybe this could be tested by the continuous
> integration tool (see below)?
> > * First pass at documentation cleanup
> > Most existing comments have been converted to POD format, using a
> > consistent template.
> Good. How would you formally describe this template (so that we can
> start using it and, hopefully, dissert for a long time about its
> pertinence, which is one of the big joys of being a developper)?
Here is a broad template:

=head1 CATEGORY

with section being either FUNCTIONS, CLASS METHODS or INSTANCE METHODS

=head2 prototype

with prototype being:
- foo($var1, $var2, ...) for a function
- Class->foo($var1, $var2, ...) for a class method
- $object->foo($var1, $var2, ...) for an instance method

Description.

A plain english sentence.

=head3 Parameters

=over

=item * I<$var1>: purpose, nature

=back

=head3 Return value

A plain english sentence.

> > A few undocumented functions/methods have also been documented.
> Yes, that's also a default we have... Most of the time, we document subs
> after we develop them. And somtimes we forget.
> > * Initial test suite
> > We now have some tests in the t/ subdirectory. Most of them are simple
> > automated tests (compilation test, pod syntax check, etc...) which
> > just brings minimal quality testing. They are also a few actual
> > functional tests for some functions defined in the Sympa::Tools
> > hierarchy.
> Great. We now have a continuous integration platform on Sourcesup
> (Hudson). I will start searching how to set it up correctly for Sympa
> and how to use your test suite.
The first thing to do is to connect the build system, so as to have 
'make check' run them. So far, I just run them manually (perl t/foo.t).

The second thing to do is to change the defaut perl test harness to use 
a junit-style one, so as to produce a result format understandable to 
hudson.

> > Indeed, that's quite a lot of changes, rather invasive. I just tested
> > installation and sympa_wizard usage so far, and I was rebuffed by
> > not-so-clear error messages while trying to launch daemons :) Should I
> > continue those tests further, and ensure my branch is sane, or can we
> > first try to merge it in its current state with other branches before
> > testing and stabilizing the result ?
> Well, there are conflicting constraints, here.
>
> I think that, when we merge, I should do it, because I have a good
> knowledge of most of the new code and I would just have to see where it
> must fit in the new organization.
> I also think we should merge first. Our own modifications will certainly
> break things in your code but it's not a big deal as you work on a pure
> development branch, with no production deadline. We have all the time we
> want to make it work.
> But I also have a lot of stabilization work to do in the 6.2 to be able
> to put in production in January (one month later than expected already).
> So I won't be able to handle the merge before the holidays.
> Then, if you have time to spend on Sympa before the beginning of
> January, it's probably better to spend it stabilizing the sympa-cleanup
> branch. at least, you could fiw the bugs coming from your own work, they
> are often easier to find out. I just hope you won't have to work on
> parts of the code that are no longer valid because Soji or I radically
> changed this part.
OK for me. I'll focus on stabilisation, isolated changes and tests then.

> All in all, it's good to see that you reached this milestone. We have
> now a cleaner, better organized code and this is a very good omen for
> the future of the project. Thanks again for you efforts!
>
> On another note: When discussing with Marc yesterday, he mad two
> suggestions:
>
>  1. take the occasion of the incoming Sympa formation we organize next
>     spring to make a Sympa hackfest. we stay a few more days on the
>     formation location and spend these days coding.
>  2. help us organizing the Sympa days. He is in charge of prospective in
>     his university and consequently has access to ressources to help
>     free software communities. We have these Sympa days in mind since a
>     while now and I think it could be usefull. The idea would be to
>     gather users to share experiences on the software. It could also
>     addresse developpers. Nothing formal: just the users, us and people
>     willing to share their own particular usage of Sympa. We could
>     probably find money to make Soji come (if he is interested of course).
Both idea seems fine for me.

BTW, I'll be in Strasbourg at the end of January for the Shibboleth 
course, so we may already have a partial face to face discussion for 
those around.

--
Guillaume Rousse
INRIA, Direction des systèmes d'information
Domaine de Voluceau
Rocquencourt - BP 105
78153 Le Chesnay
Tel: 01 39 63 58 31

Attachment: smime.p7s
Description: Signature cryptographique S/MIME