From nobody Fri Dec 03 11:52:13 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 AD70E18B207A; Fri, 3 Dec 2021 11:52:26 +0000 (UTC) (envelope-from yetoohappy@gmail.com) Received: from mail-ed1-x52c.google.com (mail-ed1-x52c.google.com [IPv6:2a00:1450:4864:20::52c]) (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 4J5B5P3LfRz3MDG; Fri, 3 Dec 2021 11:52:25 +0000 (UTC) (envelope-from yetoohappy@gmail.com) Received: by mail-ed1-x52c.google.com with SMTP id e3so10506934edu.4; Fri, 03 Dec 2021 03:52:25 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:from:date:message-id:subject:to:cc; bh=N1RrxuZI5oJwbw7RhQ5EepFQiFAbG5HPvWd/NFxMOF8=; b=QcG5ojayOGC8E9U6HEgBVCaHH+Prj/No9nru4mC+05UBb3CJqymgj+gVDGattj8Txa iW+EHYtfE07368s7+wZwRdm7VN5eJCd405fnENZl/l7goOgXC/fmdbtTJ9Ux6nQ2VEIB 7aUHjAsQVOpgPVbwFkotjdklfNjp5sSEapCk3Ofhh92Q8LkVLw8585CV36Apra5GNVnh eP+dva9wVWXSamxPrl8aMaIUDTrFxDMhZ0k7Jwb1hDAOnq/yiDW0wz+mgmrqSp9px7e0 4LVQDQ9CHZLqG5FoToFVvwGWkUzSVtz6FHTUp8NU0jjDIwuf0Tkp5QsfYsoJk8nePQP4 3aPQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:from:date:message-id:subject:to:cc; bh=N1RrxuZI5oJwbw7RhQ5EepFQiFAbG5HPvWd/NFxMOF8=; b=WG+9JQ8oAhVSsGff7kOy4ln+ZFN+7VOHeDCgEpYF+ZBzI76pm0rRzUBRSek8I6AsEg qKo3fUL/WhlRBZIfdots9iUaB+2usDAy/Rm656nu7Xa1UdfkTar80qpiEq5yTFhf8Jn6 r2/TDbycNThJLogH9TP8bjNpw/2X5qLs09oG1S8+jNNUcp3aGaK8U7L8j9LV5zbWxRyj L2x8mdCads4QFXlegKWCkNTlzpK3PIHqOPzZnQQpLJdax++YQt7mlcBc8wL8GYuxGuMG Xu32rVvgu1bK2pugs+/0XJhbpb7Me596h42zHPyf/02cdIoPWXO+pM1vs1/tmAF0jrC7 pgYA== X-Gm-Message-State: AOAM532CbyYWik8h99YCKs3bIwRnqnrVUpNjEK8qUFOVqKXyLi1HXaSW nutqYOfa48Iq8ZsUw/H8BMwRGO7lwAqDeGMTRoXcrKlx2ZqpiA== X-Google-Smtp-Source: ABdhPJyP3FalcvXCu32AfwiPlGZw05uPHNh9DgveuEnzqv0a7vs5Zv0I/00TOcjbDuZmbwou3OVeki/uRjOWzkiSCNk= X-Received: by 2002:a05:6402:50c6:: with SMTP id h6mr25202900edb.228.1638532344546; Fri, 03 Dec 2021 03:52:24 -0800 (PST) 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 From: Yetoo Happy Date: Fri, 3 Dec 2021 03:52:13 -0800 Message-ID: Subject: 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: multipart/alternative; boundary="0000000000005988d505d23c8a1c" X-Rspamd-Queue-Id: 4J5B5P3LfRz3MDG X-Spamd-Bar: / Authentication-Results: mx1.freebsd.org; dkim=pass header.d=gmail.com header.s=20210112 header.b=QcG5ojay; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (mx1.freebsd.org: domain of yetoohappy@gmail.com designates 2a00:1450:4864:20::52c as permitted sender) smtp.mailfrom=yetoohappy@gmail.com X-Spamd-Result: default: False [0.05 / 15.00]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-0.95)[-0.949]; R_DKIM_ALLOW(-0.20)[gmail.com:s=20210112]; FROM_HAS_DN(0.00)[]; FREEMAIL_FROM(0.00)[gmail.com]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[multipart/alternative,text/plain]; TO_DN_NONE(0.00)[]; R_SPF_ALLOW(-0.20)[+ip6:2a00:1450:4000::/36]; MID_RHS_MATCH_FROMTLD(0.00)[]; NEURAL_SPAM_SHORT(1.00)[1.000]; 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::52c:from]; NEURAL_SPAM_LONG(1.00)[1.000]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+,1:+,2:~]; 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-Spam: Yes X-ThisMailContainsUnwantedMimeParts: Y --0000000000005988d505d23c8a1c Content-Type: text/plain; charset="UTF-8" In https://docs.freebsd.org/en/books/handbook/cutting-edge/ I can see that at* 24.5.6.1 Merging Configuration Files* are instructions to bootstrap etcupdate 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 being 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 the documentation and all the user groups speak so highly of the handbook being complete and thorough and authoritative, are just going to* 24.5.1. Quick Start* and follow the instructions and get to step 7 and may think that even though etcupdate is different from mergemaster from the last time they used the handbook they have faith that following the instructions won't brick 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 Merging Configuration Files* because the user doesn't know that step exists or relevant to the current step and ends up unknowingly having etcupdate append "<<<< yours ... >>>>> new" to the top of the user's very important configuration files that they didn't expect the program to actually modify that way when they resolved differences nor could they predict easily because the 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 what might have happened and scrolls down to find *24.5.6.1 Merging Configuration 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 Step 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. Quick 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 right 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. The next best option is a warning at the top because it reduces the chance of 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 frustration with this problem. --0000000000005988d505d23c8a1c--