Re: Move the Handbook into source tree

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
>