Fix missing release notes

[yadij]

Vendors typically use autoreconf to rebuild Squid after patching
the Makefile.am or configure.ac sources. That tool performs an
equivalent to 'make distclean' which erases RELEASENOTES.html.

Refactor the RELEASENOTES.html creation using automake rules
with transitive dependency and clean support, and automake
variables for tools detected by ./configure are used for the
build. Ensuring that file is always able to be re-created if
missing via 'make dist' or 'make RELEASENOTES.html' commands.

The need to re-generate RELEASENOTES.html adds the linuxdoc tool
to build dependencies where it was previously only mandatory for
release maintainer to generate the "Bootstrapped sources"
tarball.

[yadij]

This problem has been around for a while, preventing certain types of patching by downstream vendors.
It has come to a head and started causing major pain with the new v7 release process.

[kinkie]

apart from this, LGTM

[yadij]

The description doesn't fit the actions - on top of what's in it, it also uses variables for tools. Which is a good thing, but it's either its own PR, or at least should be disclosed in the description

That is to ensure that tools identified by ./configure (eg when cross-compiling) are used, not anything located in the shell PATH. Updated the description to say that.

FWIW, I hit the above problem when testing the change to AC_PROG_PATH(LINUXDOC,...) and what $FALSE did without the automake conditional build. The original master code would run local linuxdoc even if the ./configure test detected it unusable, or tried to use a cross-compiler variant binary.

[kinkie]

That is to ensure that tools identified by ./configure (eg when cross-compiling) are used, not anything located in the shell PATH. Updated the description to say that.

I agree it's valuable, no question.
My only request is that this PR does two things:

• change the logic so that integrators have an easier, more reliable workflow
• add the tool detections

I'm not going to ask you to put in the work to separate them, but I do ask you to highlight there's two changes

[rousskov]

PR description: Vendors typically use autoreconf to rebuilds Squid ... That tool performs an equivalent to 'make distclean' which erases RELEASENOTES.html.

That (true) statement feels misleading in this PR context because, AFAICT, even make clean erases RELEASENOTES.html (in both official and PR sources): "Vendors" and "autoreconf" could be the motivation for this PR, of course, but the way they are currently mentioned is a red herring -- regular users rebuilding Squid under regular conditions erase RELEASENOTES.html as well. Please rephrase PR description to address this concern.

PR description: Ensuring that file is always able to be re-created if missing.

It is difficult for me to understand what this PR has changed at the top level (other than introducing a linuxdoc availability as make dist success precondition, and even that conclusion requires some guessing!).

Please rephrase PR title and description to be more specific, highlighting the top-level/primary change to RELEASENOTES.html creation targets. For example, "Prior to this changes, make ... created RELEASENOTES.html. Now, make dist creates it." Same for the primary target that erases that generated file (if that target has changed).

[rousskov]

BTW, this target and/or this particular test is broken: This target should fail when $@ does not exist but it actually succeeds. Since this PR removes ENABLE_RELEASE_DOCS protections -- exposing this code to more build cases/environments, it may be a good idea to fix this in this PR, but I do not insist on that.

[yadij]

"Works for me". Dropping a rm $@ command after the sed to replicate a failure to produce output I get this:

/usr/bin/sed \
  -e "s%[@]SQUID_VERSION[@]%8.0.0-VCS%g" \
  -e "s%[@]SQUID_RELEASE[@]%8%g" \
  -e "s%[@]SQUID_RELEASE_OLD[@]%$(( 8 - 1 ))%g" \
  < ../../../doc/release-notes/release-8.sgml.in >release-8.sgml ; rm -f release-8.sgml
test `grep -c "@SQUID" release-8.sgml` -eq 0
grep: release-8.sgml: No such file or directory
/bin/bash: line 1: test: -eq: unary operator expected

[yadij]

PR description: Vendors typically use autoreconf to rebuilds Squid ... That tool performs an equivalent to 'make distclean' which erases RELEASENOTES.html.

That (true) statement feels misleading in this PR context because, AFAICT, even make clean erases RELEASENOTES.html (in both official and PR sources): "Vendors" and "autoreconf" could be the motivation for this PR, of course, but the way they are currently mentioned is a red herring -- regular users rebuilding Squid under regular conditions erase RELEASENOTES.html as well. Please rephrase PR description to address this concern.

The move to DISTCLEANFILES += RELEASENOTES.html in commit now prevents make clean removing the file. Only an make distclean, autoreconf or manual rm command removes the RELEASENOTES.html file.

$ ../configure && make && ls -1 *.html
RELEASENOTES.html

$ make clean >/dev/null && ls -1 *.html
RELEASENOTES.html

$ make distclean >/dev/null && ls -1 *.html
ls: cannot access '*.html': No such file or directory

PR description: Ensuring that file is always able to be re-created if missing.

It is difficult for me to understand what this PR has changed at the top level (other than introducing a linuxdoc availability as make dist success precondition, and even that conclusion requires some guessing!).

At the top level the dependency chain for dist target is now explicitly dist -> RELEASENOTES.html -> html -> html-recursive -> -C doc/ { html -> html-recursive } -> -C doc/release-notes/ { html -> html-recursive -> html -> $(DOC).html -> $(DOC).sgml -> $(DOC).sgml.in }.
It is no longer a manual (release maintainer scripted) make -C doc/release-notes/ release-N.html && make dist command.

Please rephrase PR title and description to be more specific, highlighting the top-level/primary change to RELEASENOTES.html creation targets. For example, "Prior to this changes, make ... created RELEASENOTES.html.

Not as easy as that. It is more work than I am willing to invest just for a commit message, to track down all the possible targets that lead to the multiple old cp ... RELEASENOTES.html commands. Many different commands could create it, some of which would fail with an error, most would not (thanks to the @if being removed by this PR).

Now, make dist creates it." Same for the primary target that erases that generated file (if that target has changed).

Done. Only the way to create it has changed now.