RE: Change Announcements (was Re: TLS/SSL-ceritificate & Replication v2.1.3)

["Howard Chu" <hyc@symas.com>]

> -----Original Message-----
> From: owner-openldap-software@OpenLDAP.org
> [mailto:owner-openldap-software@OpenLDAP.org]On Behalf Of jimd@siu.edu

> I wholeheartedly agree! An "OperationalChanges" document should be
> supplied with each OpenLDAP release that lists/details/points out all of
> the significant/important changes in operational characteristics and/or
> requirements for OpenLDAP.

I don't mean to detract from the spirit of what you're saying, but my first
thought is - what is an Operational Change? What is a significant one? Any
bug fix that prevents an undesirable behavior sounds like an operational
change to me. It's a judgement call; who decides what is significant?

Remember that this is volunteer-driven work. If you think something is
missing, the first step is to raise it for discussion, as you're doing here.
But if you expect someone else to absorb your wishlist and then "make it so,"
I think you're in the wrong place. This project grows through contributions
from the user community. As the saying goes, "free software isn't free." If
you find it useful and you want to see it improve you have an obligation to
do your part to make that happen.

> I do go through the CHANGES and ANNOUNCEMENT files, but they don't carry
> such operational changes. They may include something about a problem
> that relates to an operational change, but not any indication of a
> change in operational behaviour or requirements.

I think your main gripe is with the jump from 2.0.x to 2.1.x. I'd have to
agree that there needs to be a formal document listing the operational
differences. Within minor revisions I don't think there's a serious issue
here; minor revs are mostly bug fixes and the ITS#s of the bugs are available
for your reference.

> This is not something that should be relegated to an FAQ, and does
> nothing to improve the usability of OpenLDAP, which IS what I want to
> see. This is even more critical when making large version jumps between
> installations.

I want to improve the usability of OpenLDAP too. Obviously my interpretation
of what that means may differ from yours, but the basic point is the same.
Because I wanted something badly enough, I put in the energy required to
bring it about. How badly do you want it? Where are your productive energies?
(That's a question directed to the entire list, not just you personally.)

> It took me days to figure out that V2.1.3 had activated strict control
> over attribute USAGE declarations. Yes, USAGE is listed in the RFC's,
> but until some V2.x release of OpenLDAP it was not enforced. I had to do
> a major change of attribute and objectclass layout for my pre-V2.1.x
> release data. If an "OperationalChanges" file/document had been
> available with the distribution that clearly identified this change in
> operational behaviour/requirements, then I could have saved myself a LOT
> of time pullying my hair out, trying to figure out what was wrong with
> my previously working LDAP data. (posts to the mailing list were either
> not accepted, or not answered)

There is a learning curve here for both the users and the developers. I've
tried to push meaningful error messages in whenever I encounter an unexpected
failure. Of course what's meaningful to me may seem like gibberish to someone
else. And the core team is rather small, so the sum of our usage patterns
probably doesn't exercise the entire code base with equal rigor. You as users
are bound to run into situations that we haven't encountered. The
documentation has been far out of date wrt the code since who-knows-when.
There's a huge amount that ought to be written, but we only have so much
time, and it's up to you to provide feedback that indicates where time should
be allocated. We have to learn from your experiences as well as our own.

A lot of questions go by that don't get answered. Some have been answered
before, some are off-topic, some are real stumpers, and some just get missed
because we don't have enough time to deal with them. Also, in recent weeks,
the list server itself was down, and I suspect that a large number of
questions went unanswered... That's life.

> Mailing lists are transitory. FAQ's are incomplete, out of date, and
> usually more specific to a particular action taken rather than a
> disclosure of a new operational requirement. They also are not readily
> available when working in a standalone environment, are difficult to
> search, and in many cases - just not useful. Online FAQ's are also not
> easy to work with or correct, and they usually are very limited to scope
> and length of entries. Lastly, many entries may not clearly identify the
> real problem or a real S/W change as the "reporter" may not really know
> what was causing the problem that thay are commenting on.

Very little on the Net today is completely transitory - you will find it
archived in any number of places. Yes, it can be difficult to sift through
all the volume and digest it into something coherent. Guess what - it's just
as hard for us as it is for you, and we would much rather be spending our
time fixing bugs and extending features. When you've chased down a problem
and found the solution, post it somewhere.

I should pause for a moment to note that I've seen more and more posts and
documents from other sources providing useful answers on this list, so this
may be preaching to the choir in some cases. If so, forgive me for belaboring
the point.

The FAQs may be out of date, but again, you have the ability to fix that
yourself, and add material that brings it up to date. I'm not disagreeing
about the need for a ready document, but I think the FAQ is an extremely easy
way for you to put answers up where they can be seen. (You can also submit
documents into the ITS for review and incorporation.) Just saying that the
FAQ is not useful sounds like a cop-out to me. It has the potential to be
useful, and it grows from your contributions.

> I would like to see an OperationalChanges document that identifies each
> major operational change by release version. I can then plan,
> accordingly, how to go about upgrading any particular version. If I

At present there are 25 revisions in the 2.0 stream and 3 revisions in 2.1,
so a document describing differences between any particular version would
have 15625 sections. I'm not keen on writing this any time soon. Are you?
(And you thought maintaining a half-dozen implementations was bad...) I think
your request here is too broad, you need to be more specific about which
versions you're interested in.

> still have questions, then I will "hit" the mailing lists, where I will
> be more informed as to what I am looking for, and responses will
> (hopefully) be more relevant to the changes in question, rather than
> just recommendations of trying "this or that".

You have complete access to as much information as exists. The only way for
you to become more informed than you already are, is to go and read it. The
Changes document lists bugs that have been fixed, and you have the ability to
read the bug reports. You have access to the mailing list archives where any
issues are discussed. You have access to the CVS repository, which allows you
to examine the change history/log messages for individual files. These are
exactly the same resources that we have to use when we deal with questions.
When someone asks about a bug/feature and I post "this was fixed/changed
around year-month-day in revision xx.yy.zz" I got that answer by digging thru
the source tree, mailing list archives, etc., until I found the relevant
files. That's pretty time-consuming, no matter who does the digging.

> On 24 Aug, Will Day wrote:
> > A short time ago, at a computer terminal not so far away, Kurt
> D. Zeilenga wrote:
> >>>In particular, I'm thinking about things like the above
> >>>change in cert verification behavior, as well as the change in SASL DN
> >>>format.

> >>Sounds like the start of a FAQ answer.  Feel free to add
> >>useful answers to the FAQ.  It is interactive.

> > Hmm, yes an FAQ entry would be better than nothing, but the idea I was
> > trying to get across was that ideally this should be information provided
> > at release, by those who made the changes - rather than after release, by
> > those who found the changes.

Yes, sounds great. But since you're saying that at the moment you have
"nothing" I think you should take what you can get (the FAQ) as a Starting
Point, and go from there. Everything has to begin somewhere. In some respect
I think it's unrealistic for anyone to expect comprehensive documentation to
come out of a group of volunteer software developers. We write code, not
prose. That may be the heart of the matter, and a satisfactory solution won't
emerge until a competent tech-writer steps up who's motivated enough to dive
in.

  -- Howard Chu
  Chief Architect, Symas Corp.       Director, Highland Sun
  http://www.symas.com               http://highlandsun.com/hyc
  Symas: Premier OpenSource Development and Support