From nobody Tue Sep 07 09:16:49 2021 X-Original-To: freebsd-current@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 53AA3179C55F for ; Tue, 7 Sep 2021 09:16:51 +0000 (UTC) (envelope-from theraven@FreeBSD.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4H3fm31tSxz4lcP for ; Tue, 7 Sep 2021 09:16:51 +0000 (UTC) (envelope-from theraven@FreeBSD.org) Received: from smtp.theravensnest.org (smtp.theravensnest.org [45.77.103.195]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) (Authenticated sender: theraven) by smtp.freebsd.org (Postfix) with ESMTPSA id 1A5452C75F for ; Tue, 7 Sep 2021 09:16:51 +0000 (UTC) (envelope-from theraven@FreeBSD.org) Received: from [192.168.1.202] (host86-148-130-214.range86-148.btcentralplus.com [86.148.130.214]) by smtp.theravensnest.org (Postfix) with ESMTPSA id B23902C91D for ; Tue, 7 Sep 2021 10:16:50 +0100 (BST) Subject: Re: Move the Handbook into source tree To: freebsd-current@freebsd.org References: From: David Chisnall Message-ID: Date: Tue, 7 Sep 2021 10:16:49 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.13.0 List-Id: Discussions about the use of FreeBSD-current List-Archive: https://lists.freebsd.org/archives/freebsd-current List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-current@freebsd.org MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-GB Content-Transfer-Encoding: 7bit X-ThisMailContainsUnwantedMimeParts: N 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 >