[squid-dev] FYI: changes to trunk Release Notes

[Amos Jeffries]

I have now almost completed an update to the automation behind the
release notes that means all official branches of Squid will always have
release notes available, and that tarballs generated will have a copy
available for downloaders use.

For all of us as developers this raises the importance of updating the
SGML file whenever we add a new UI feature to Squid. Most of us have
been very lax at this for years.

Basically if you are committing a patch (any patch) that changes any of
the following items then you need a release notes entry for it:


* any little change to ./configure parameters

 - including things that affect the values parameters take,


* changes to what environment variables are handled by ./configure


* any little change to squid.conf directives

 including changes to what parameters and options each one can accept,
and particularly if an existing ones behaviour changes.


If its output related, mgr reports, logs etc. the relevant wiki pages
need updating after commit, not the release notes. Though if its part of
a bigger feature mentioning things like that in the new features section
is useful.


There are some guidelines to be aware of when editing:

 1) which release notes need updating ?

 - assume the latest trunk version.

 - BUT, I am trying to treat 3.5 as a sort of LTS (but only loosely) and
accepting very minor squid.conf UI tweaks (like logformat code
additions) where the existing install base can continue operating with
no behaviour change if they omit the new option.


2) SGML indentation and syntax.

 - Its pretty obvious. Similar to HTML, but only some tags need closing.

 - However the style I've worked up for cros-release consistency does
use TAB indentation in the lists of ./configure and squid.conf changes.

 - and 3 SP characters to indent paragraphs to the end of '<p>' tag.
With separate paragraph for each flagged detail.

 - if in doubt please look at the existing stable branch files to see
how things are done. Especially if the section you are adding to is
empty, like they will be at the start of a new branches lifecycle.



I will be starting to ask for notes again in some audits. But please be
proactive.


PS. as far as I know the current Squid-4 release notes are up to date in
regards to squid.conf and major features (but not ./configure options).
More pairs of eyes looking them over will help.

Cheers
Amos