From nobody Fri Dec 24 03:08:45 2021 X-Original-To: freebsd-doc@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 2F833191EE9F; Fri, 24 Dec 2021 03:09:00 +0000 (UTC) (envelope-from yetoohappy@gmail.com) Received: from mail-lf1-x132.google.com (mail-lf1-x132.google.com [IPv6:2a00:1450:4864:20::132]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1D4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4JKsTl3hVBz3Pr4; Fri, 24 Dec 2021 03:08:59 +0000 (UTC) (envelope-from yetoohappy@gmail.com) Received: by mail-lf1-x132.google.com with SMTP id k21so16373023lfu.0; Thu, 23 Dec 2021 19:08:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc:content-transfer-encoding; bh=Ff2hmuOMYXFXDvcbIAkeqIKyQ2Fr71DzheewzljoKI4=; b=O7/kX9/ipHYYgNZCrd6triz3cP8/61n/+RsTbZz2sYSwROnGhNFd18l1buukGB4UAk DMsJ4AQrMzwDIZ9TZcVbI39vyqSn162/e99nEeZdO7ZutMdicIqfnlz5hFefhx9Okmjp c/PmeSh7I6GwVtLBmQNpfwSKR8T5MVxLJngOvVQKTFBzea/yumu60iJJPXo904PiGq1t dNamjQKZx9yXw94kst4cmlP4GMLxEnH51BnSr5tdrIF89BumqZX+uZbRg83zTjvjt1fk Q9DD6xrHx0UskKZ2u/S6/RYw8+ygBccgrjSymNMJuMRDkVa1PLMmyeG3RJZ0NVP8gtxK In0w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=Ff2hmuOMYXFXDvcbIAkeqIKyQ2Fr71DzheewzljoKI4=; b=kr1+/qqC/bBZ1F49NIrAF6dQVONFI/CZA4OiEd/pHWOimdXbMjl/cPGkC8wFDXMqz6 z3IFU4M7ZHZYILveKKxYhH9r9WIaGu0RsJ1IZdv6dvqipyHNZx/ldBjUiaKSwHGMYI72 b0IR4Osgq11M8u4K0y2qG5YcfNiFfiWnwRvnqOrhKnb8k2zytX/1RmAEpNcS8jBLFDSL tpJf1e18xuH92ZQnhA6l4rSLSlf+9Yf8YiSvKulcwsUzESBuiTWBvaEkz3cda/uvWu/c PLU6mkdmstkKKXVi9QvRZtFZgqcE4xlwHRG341dSgbcZ5QufWxyxLgJ+mDAlWCgV1Ybu lQHw== X-Gm-Message-State: AOAM532r1EkSucT8uKmoR60Gm1NcnWCe44xN2jojb/GLcQWPaOPKTyWC sw2w7ZclAlGBIhrONKbS3F/X9wAwDYoboid5i3OJNftb X-Google-Smtp-Source: ABdhPJybxWVsPOtCw/p9vtMtPMacNCI5PIH9MCg4scWxU2U9T+DWhyt2p4hyStkFSfsrGOFRmYsbsJZDQecV7ThsRo8= X-Received: by 2002:a05:6512:1304:: with SMTP id x4mr3865146lfu.484.1640315337235; Thu, 23 Dec 2021 19:08:57 -0800 (PST) List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org MIME-Version: 1.0 References: In-Reply-To: From: Yetoo Happy Date: Thu, 23 Dec 2021 19:08:45 -0800 Message-ID: Subject: Re: Make etcupdate bootstrap requirement due to previous mergemaster usage more clear in handbook To: freebsd-doc@freebsd.org Cc: freebsd-current@freebsd.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: 4JKsTl3hVBz3Pr4 X-Spamd-Bar: --- Authentication-Results: mx1.freebsd.org; dkim=pass header.d=gmail.com header.s=20210112 header.b="O7/kX9/i"; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (mx1.freebsd.org: domain of yetoohappy@gmail.com designates 2a00:1450:4864:20::132 as permitted sender) smtp.mailfrom=yetoohappy@gmail.com X-Spamd-Result: default: False [-3.18 / 15.00]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-0.99)[-0.994]; R_DKIM_ALLOW(-0.20)[gmail.com:s=20210112]; FROM_HAS_DN(0.00)[]; R_SPF_ALLOW(-0.20)[+ip6:2a00:1450:4000::/36:c]; FREEMAIL_FROM(0.00)[gmail.com]; MIME_GOOD(-0.10)[text/plain]; TO_DN_NONE(0.00)[]; NEURAL_HAM_LONG(-0.19)[-0.185]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MID_RHS_MATCH_FROMTLD(0.00)[]; DKIM_TRACE(0.00)[gmail.com:+]; RCPT_COUNT_TWO(0.00)[2]; DMARC_POLICY_ALLOW(-0.50)[gmail.com,none]; RCVD_IN_DNSWL_NONE(0.00)[2a00:1450:4864:20::132:from]; NEURAL_HAM_SHORT(-1.00)[-1.000]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; FREEMAIL_ENVFROM(0.00)[gmail.com]; ASN(0.00)[asn:15169, ipnet:2a00:1450::/32, country:US]; RCVD_COUNT_TWO(0.00)[2]; RCVD_TLS_ALL(0.00)[]; DWL_DNSWL_NONE(0.00)[gmail.com:dkim] X-ThisMailContainsUnwantedMimeParts: N On Fri, Dec 3, 2021 at 3:52 AM Yetoo Happy wrote: > > In https://docs.freebsd.org/en/books/handbook/cutting-edge/ I can see tha= t at 24.5.6.1 Merging Configuration Files are instructions to bootstrap etc= update if switching from mergemaster. This is really convenient and really = useful, EXCEPT for that fact that it is placed in a part of the handbook a = little ways after installation would complete. The critical issue here bein= g that, due to this information not being higher up, a user who is looking = at the handbook to update from source and are trusting the handbook because= they have faith that it won't play any dirty tricks on them, because all t= he documentation and all the user groups speak so highly of the handbook be= ing complete and thorough and authoritative, are just going to 24.5.1. Quic= k Start and follow the instructions and get to step 7 and may think that ev= en though etcupdate is different from mergemaster from the last time they u= sed the handbook they have faith that following the instructions won't bric= k their system. This user will instead find that faith in general is just a= very complex facade for the pain and suffering of not following 24.5.6.1 M= erging Configuration Files because the user doesn't know that step exists o= r relevant to the current step and ends up unknowingly having etcupdate app= end "<<<< yours ... >>>>> new" to the top of the user's very important conf= iguration files that they didn't expect the program to actually modify that= way when they resolved differences nor could they predict easily because t= he diff format is so unintuitive and different from mergemaster. Now unable= to login or boot into single user mode because redirections instead of the= actual configuration is parsed the user goes to the handbook to find out w= hat might have happened and scrolls down to find 24.5.6.1 Merging Configura= tion Files is under 24.5.6. Completing the Update. What a mocking section? = Completing the update? How could I have completed the update if I was on St= ep 7 of Quick Steps? The user now may feel cheated, jaded, or insulted and = wonder what the fuss is all about with this hyped documentation. > > Here's a solution: Make a red warning notice at the very top of 24.5.1. Q= uick Start and refer to 24.5.6.1 Merging Configuration Files and make clear= this is for step 7. Another solution is, if possible, put that red warning= notice next to step 7 or step 7 in the grey section or red/pink section of= the quick start box area, I personally would prefer a warning with text ri= ght next to step 7 in the red/pink part of the quick start box, but I'm not= sure if that's possible or respecting the documentation design paradigm. T= he next best option is a warning at the top because it reduces the chance o= f a user following instructions and missing that step because they haven't = scrolled to that point yet. > > I'm sorry if this comes across as an angry potentially combative message,= but I just wanted to make clear where and what the problem is and my frust= ration with this problem. Around the time I made this post, I created a patch that I believe resolves the issue with the documentation. Here is the PR for posterity: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=3D260253