Thinking about others after you (Re: [index] RDN)

[Alex Karasulu <ak...@apache.org>]

On Thu, Mar 22, 2012 at 8:33 PM, Emmanuel Lécharny <el...@gmail.com>wrote:

> Hi,
>
> a second mail about index, specifically those related to the manipulation
> of the DN.
>
> RDN index
> ---------
>
> First of all, let's present the data structure used for the Rdn index.
> It's not exactly a RDN index, as the key is a composite structure : the
> ParentIdAndRDN (it contains the entry ID of it's parent in the DIT and the
> entry's RDN). More, it's not exactly a RDN that we store, as for the
> partition root, we store the partition DN (which can contain more than one
> RDN).
>
>
<speaking-generally-with-pmc-hat-on not-in-response-to="Emmanuel">
These changes are some of the largest changes since the search algorithm
has been designed over 10 years ago and impact one of the more complex
parts of the server.

I am appalled at this not being documented when the changes were made. I
personally took a lot of effort in making sure the documentation was
pretty, informative and allowed new comers and those new to this region of
the code to understand how it worked. Those who made these changes
benefited from my thorough documentation. They need to carry on the
tradition and make sure others after them also benefit, and don't detriment
from it by documenting their changes.

Why is it that others do not feel this way? I can understand straight
forward areas that document themselves well in code alone but people need
to consider new comers that want to get into the more complex code. They
should update these parts of the documentation even if it's not pretty
documentation.

Also it's no excuse to say we need the 2.0 to stabilize otherwise the docs
will change. Over the past ten years very little has changed in our search
algorithm. So this is not a region of code that we f**k with often since
it's so critical to the servers operation.

Committers making changes to "complex" regions of code should think about
others that come after them to maintain their code. This is just good
community citizenship. Those that don't really don't care about the
community. Being polite is not just about correct speech with words like
sir and madam. It's ones actions considering others.
</speaking-generally-with-pmc-hat-on>

Sorry Emmanuel this was a bit off topic but it's something we all need to
consider. I will try to respond to your comments later. I'm not immediately
available these days but I will not forget to answer these emails even if
it takes me some time.

-- 
Best Regards,
-- Alex

Re: Thinking about others after you (Re: [index] RDN)

[Emmanuel Lécharny <el...@gmail.com>]

Le 3/26/12 2:57 PM, Alex Karasulu a écrit :
> On Thu, Mar 22, 2012 at 8:33 PM, Emmanuel Lécharny<el...@gmail.com>wrote:
>
>> Hi,
>>
>> a second mail about index, specifically those related to the manipulation
>> of the DN.
>>
>> RDN index
>> ---------
>>
>> First of all, let's present the data structure used for the Rdn index.
>> It's not exactly a RDN index, as the key is a composite structure : the
>> ParentIdAndRDN (it contains the entry ID of it's parent in the DIT and the
>> entry's RDN). More, it's not exactly a RDN that we store, as for the
>> partition root, we store the partition DN (which can contain more than one
>> RDN).
>>
>>
> <speaking-generally-with-pmc-hat-on not-in-response-to="Emmanuel">
> These changes are some of the largest changes since the search algorithm
> has been designed over 10 years ago and impact one of the more complex
> parts of the server.
>
> I am appalled at this not being documented when the changes were made. I
> personally took a lot of effort in making sure the documentation was
> pretty, informative and allowed new comers and those new to this region of
> the code to understand how it worked. Those who made these changes
> benefited from my thorough documentation. They need to carry on the
> tradition and make sure others after them also benefit, and don't detriment
> from it by documenting their changes.
>
> Why is it that others do not feel this way? I can understand straight
> forward areas that document themselves well in code alone but people need
> to consider new comers that want to get into the more complex code. They
> should update these parts of the documentation even if it's not pretty
> documentation.
>
> Also it's no excuse to say we need the 2.0 to stabilize otherwise the docs
> will change. Over the past ten years very little has changed in our search
> algorithm. So this is not a region of code that we f**k with often since
> it's so critical to the servers operation.
>
> Committers making changes to "complex" regions of code should think about
> others that come after them to maintain their code. This is just good
> community citizenship. Those that don't really don't care about the
> community. Being polite is not just about correct speech with words like
> sir and madam. It's ones actions considering others.
> </speaking-generally-with-pmc-hat-on>
>
> Sorry Emmanuel this was a bit off topic but it's something we all need to
> consider. I will try to respond to your comments later. I'm not immediately
> available these days but I will not forget to answer these emails even if
> it takes me some time.
>
I have little to add to what Alex says, except that I do agree 100%. I 
have spent considerable amount of time documentng part of the code I 
even didn't wrote, something I don't really like to do for two reasons :
- first, you don't have a clear vision on what was in the original 
designer's mind, so you can just extrapolate
- second becaus eit takes a hell of time I don't have, so it collides 
with what I have to do on other aspects of the project

Yes, I know, documentation sucks. It's hard, it's always a moving 
target, and nobody RTFM anyway. Except that we *do* read the FM from 
time to time when we jump onto a part we don't know.

The server is a MASSIVE piece of code now (above 600 000 slocs). It's a 
10 years old effort, with many people having contributed, and each of us 
in some area not known by most of the others.

It's absolutely critical that we document the part that are added when 
it's impossible to understand what they are doing by simply read the code.

We use Confluence atm, and it's pretty easy to add some documentation 
there. In the near future, we will probably move to something different, 
but in the mean time, there is no reason we don't spend the minimal time 
to write there the ideas that are driving our code.

The Mailing List is a perfect place to *discuss* modifications, or 
suggesting modification, but it's not a substitute for documentation. 
Keep in mind that what we are adding in the code will remain there for a 
very long period.

If you wonder where to add the doco, then it's simple : use the 1.5 
space (https://cwiki.apache.org/confluence/display/DIRxSRVx11/Index), 
and morr specifically, the Developper Guide 
(https://cwiki.apache.org/confluence/display/DIRxSRVx11/ApacheDS+v1.5+Developer%27s+Guide)

Thanks !

-- 
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com