Le 3/26/12 2:57 PM, Alex Karasulu a écrit :
On Thu, Mar 22, 2012 at 8:33 PM, Emmanuel Lécharny<[email protected]>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
