- I think the excellent ESI processing changes documentation should
  be promoted from changes.rst. I think it is more helpful to
  users planning their upgrade, because it gives better advice.

- I thought we could be a little more verbose on abstract UDSes
  and the weak Last-Modified changes.

- The director .release callback was not yet mentioned

All other changes are not worth mentioning I guess.

At least for me, this makes it easier to check if we missed anything.

- cross-reference parameter and vcl variable

- clarify that a zero value means no limit (I found 'no buffering' confusing when
  in fact the full object is buffered, potentially)

- improve wording, hopefully

The square brackets were probably the result of copy-pasta from vcl.load
where the initial state is indeed optional.

Before this patch, layered directors needed to be destroyed top to
bottom, and whenever that order was missed, we would panic, because a
to-be-destroyed director still had references to it.

One special case where this issue would always trigger are looped
directors. Those should not be used and will cause havoc, which is a
separate issue #3899. But we should still be able to unconfigure such
a configuration.

We solve the destruction order issue by making it a two step process:

When a director is destroyed through VRT_DelDirector, a new release
function is called, which has to disassociate any backends. The
director then loses a reference, and when all references are gone, the
destroy function is called.

The new callback would not be necessary for the cases in varnish-cache
today, directors could simply disassociate any backends before calling
VRT_DelDirector. But this would complicate or even make impossible
transfer of director ownership, where the code responsible for
creating a director is not the same as the one calling
VRT_DelDirector(). As a side effect, it also helps clarity.

Fixes #3895

The last reference to a director might go away with VRT_DelDirector
_or_ VRT_Asssign_Backend, which the former needs to account for.

We assert for the VDIR_FLG_NOREFCNT case that there was only one
reference such that a single deref yields no reference left.

Part one of the fix for #3895

This is in preparation of follow-up commits. Reasoning:

- in both call sites, we already use the struct vcldir *
- once call site actually used TAKE_OBJ semantics, but those
  can easily be moved

Use a local vdir variable for clarity like elsewhere in the code.
Use the lock in vdir, not the pointer to it in VCL_BACKEND for
consistency with VRT_DelDirector() a few lines above.

I noticed that users, apparently, have no way of finding out what
their distribution configured?

Now that we broke the VSL format, this is the time to act.

This prevents VUTs from attempting to read incompatible formats, while
preserving the current header size, aligning it with the SHMLOG header
at the format number 2.

It will no longer be valid for assignments, and in one case the
assignment was superfluous.

This means an older varnishlog can no longer read logs from a live
current varnishd server, and vice versa. It used to be interesting
to use a more modern VUT to process logs for example to get better
performance or new features like generalized -E.

Restructured so that:

* 'Upgrading' is limited to work that has to be done to upgrade from
  a current deployment to the new version.

* 'Changes' is a comprehensive, user-level description of changes and
  new features.

Conflicts:
	doc/sphinx/whats-new/index.rst

We keep s as a pointer to the start of an unaltered section and
move e to be able to call VSB_bcat() when a backslash is encountered
or substitution is complete.