From mboxrd@z Thu Jan 1 00:00:00 1970 From: ng0 Subject: Re: We need an RFC procedure [Re: Services can now have a default value] Date: Sat, 22 Apr 2017 10:08:11 +0000 Message-ID: <20170422100811.mr3t5rgh6n44xvdk@abyayala> References: <87shl9qo7h.fsf@gnu.org> <877f2go3wn.fsf@zancanaro.id.au> <877f2gksbs.fsf@gnu.org> <8737d32abz.fsf@zancanaro.id.au> <87bmrr4ghh.fsf@gnu.org> <874lxjnzyx.fsf@zancanaro.id.au> <87bmrp8lk6.fsf@gnu.org> <8737d1nxbd.fsf@zancanaro.id.au> <20170422004634.4oedqmsebpctjqk4@abyayala> <878tmsud8m.fsf@elephly.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:47869) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1d1rxp-0003GQ-9H for guix-devel@gnu.org; Sat, 22 Apr 2017 06:08:26 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1d1rxl-0003XM-QI for guix-devel@gnu.org; Sat, 22 Apr 2017 06:08:25 -0400 Received: from perdizione.investici.org ([94.23.50.208]:38890) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1d1rxk-0003WZ-QK for guix-devel@gnu.org; Sat, 22 Apr 2017 06:08:21 -0400 Content-Disposition: inline In-Reply-To: <878tmsud8m.fsf@elephly.net> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Ricardo Wurmus Cc: guix-devel , Carlo Zancanaro Ricardo Wurmus transcribed 0.7K bytes: >=20 > ng0 writes: >=20 > > I want an formal, publicly tracked (not *just* on the mailinglist) RF= C (like in Rust or similar projects) procedure for all things which > > can break currently existing configurations. Introducing these change= s would > > require to document properly what needs to changed so that people can= read > > about how to fix the mistakes. >=20 > [=E2=80=A6] >=20 > API changes are usually explained in the release announcement=E2=80=99s > changelog. This doesn=E2=80=99t really help between releases, though. = So, > either we release more often (yay!) or we support the old APIs until th= e > next release (boo!). Okay, then let me be more specific as you skipped the last part of the message, which explained my intention. Let's take this thread, starting at "https://lists.gnu.org/archive/html/guix-devel/2017-04/msg00329.html". Ludovic worked on something, pushed it, did some changes to the relevant documentation but further examples in the documentation which are now affected weren't fixed with the push. We spent time answering questions about broken configurations, assuming everyone who uses GuixSD now and in the future has a fairly competent knowledge of Guile, explaining chang= es which could have been avoided - or at least reduced in frequency of quest= ions asked - by changing examples. If Ludovic would've presented this change before applying it, it would've been one of the obvious problems: don't just document the change, change further documentation sections which rely on this. This way we don't have a documentation which presents people examples but contradicts itself lat= er on. I'm pretty sure I don't have to tell you that casual users would not wast= e their time with getting to the solution, and admins want something which = in case of breakage documents the changes before they happen. Announcing the changes after the discussion about the changes happened is another thing. Gentoo sent out "Mails" (local mail) which was then displayed and kept in the system of the user and it would be visible in the portage (comparable to "guix package") application. A bug report on "oh no, my system imploded!" would then ask, have you rea= d the announcement message? And archlinux does it in a similar fashion, for both systems changes are made visible in news on the website. Even when we would have a "stable" and "unstable" variant, documenting ch= anges and explaining how to solve problems arising from them should come natura= l and in our case it shouldn't involve implied conclusions but rather a good se= t of examples. --=20 PGP and more: https://people.pragmatique.xyz/ng0/