Hi,
I think there are two conflated things here:
- Moving the handbook into the source tree.
- Creating branches in the handbook that track particular releases.
The first one is largely irrelevant to anyone other than people
contributing to the handbook, so I'll focus on the second:
This is quite an easy way of having a per-release snapshot but it means
that the handbook will diverge for different releases over time. If the
new docs are documenting things that are new, that's fine, but if new
docs are added to -CURRENT for things in a release, then they will need
to follow the same MFC process as code flowing from current to releases,
which brings up the potential of merge conflicts and so on.
This is made even more complex in cases where code is MFC'd. Typically
(unfortunately) docs are added to the handbook after a feature is
committed and so things will need to be MFC'd at the same time as other
features are MFC'd or later if they're written after the original MFC.
I see two possible workflows, the current and the proposed one, both of
which have disadvantages:
- With the current workflow, you need to explicitly track which
release things apply to in the document.
- With your proposed workflow, you need to explicitly track which
release things apply to by merging them at the correct time.
It's not clear to me that either of these is necessarily easier than the
other.
David
On 07/09/2021 08:01, Mehmet Erol Sanliturk wrote:
Dear All ,
in many of my messages to FreeBSD mailing lists I am mentioning the
following view :
"Please move the Handbook into source tree , and
Maintain it with respect to current release without mixing sliding
releases : If you do this ,
maintenance of a correct Handbook is IMPOSSIBLE because maintenance of
associated IF statements about releases .
"
When we look at the following web pages , we see the following :
https://www.freebsd.org/cgi/man.cgi
FreeBSD Manual Pages
In the second box of "All sections" line , there are lines about all of
the FreeBSD releases
with many more other systems .
In spite of this , in the following page :
https://docs.freebsd.org/en/books/handbook/
FreeBSD Handbook
The FreeBSD Documentation Project
"
Abstract
Welcome to FreeBSD! This handbook covers the installation and day to day
use of
FreeBSD 13.0-RELEASE, FreeBSD 12.2-RELEASE and FreeBSD 11.4-RELEASE. ...
"
A Handbook which ( for me , exactly , for the others , perhaps ) with many
errors ...
I think that , it is NOT extraordinarily a difficult process to move the
Handbook into source
tree and maintaining it with respect to per release and insert into the
above web page a part
similar to the manual pages to display the requested Handbook with respect
to releases .
In the present case , previous handbooks are lost , because of the
difficulty of finding them .
Thank you very much and my best wishes for you and humanity in these
pandemic days ...
Mehmet Erol Sanliturk
