Re: We need an RFC procedure [Re: Services can now have a default value]

[ng0 <contact.ng0@cryptolab.net>]

Ricardo Wurmus transcribed 0.7K bytes:
> 
> ng0 <contact.ng0@cryptolab.net> writes:
> 
> > I want an formal, publicly tracked (not *just* on the mailinglist) RFC (like in Rust or similar projects) procedure for all things which
> > can break currently existing configurations. Introducing these changes would
> > require to document properly what needs to changed so that people can read
> > about how to fix the mistakes.
> 
> […]
> 
> API changes are usually explained in the release announcement’s
> changelog.  This doesn’t really help between releases, though.  So,
> either we release more often (yay!) or we support the old APIs until the
> 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 changes
which could have been avoided - or at least reduced in frequency of questions
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 later
on.
I'm pretty sure I don't have to tell you that casual users would not waste
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 read
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 changes
and explaining how to solve problems arising from them should come natural and
in our case it shouldn't involve implied conclusions but rather a good set
of examples.
-- 
PGP and more: https://people.pragmatique.xyz/ng0/