From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from lists.gentoo.org ([140.105.134.102] helo=robin.gentoo.org) by nuthatch.gentoo.org with esmtp (Exim 4.50) id 1EYRyS-0008Nl-FC for garchives@archives.gentoo.org; Sat, 05 Nov 2005 17:37:05 +0000 Received: from robin.gentoo.org (localhost [127.0.0.1]) by robin.gentoo.org (8.13.5/8.13.5) with SMTP id jA5HaLAn011508; Sat, 5 Nov 2005 17:36:21 GMT Received: from smtp.gentoo.org (smtp.gentoo.org [134.68.220.30]) by robin.gentoo.org (8.13.5/8.13.5) with ESMTP id jA5HYZFt027199 for ; Sat, 5 Nov 2005 17:34:35 GMT Received: from 82-41-57-20.cable.ubr08.edin.blueyonder.co.uk ([82.41.57.20] helo=snowdrop.home) by smtp.gentoo.org with esmtpa (Exim 4.43) id 1EYRw2-00020E-Ob for gentoo-dev@lists.gentoo.org; Sat, 05 Nov 2005 17:34:35 +0000 Received: from localhost.home ([127.0.0.1] helo=snowdrop.home) by snowdrop.home with esmtp (Exim 4.54) id 1EYRvx-0008M7-96 for gentoo-dev@lists.gentoo.org; Sat, 05 Nov 2005 17:34:29 +0000 Date: Sat, 5 Nov 2005 17:34:26 +0000 From: Ciaran McCreesh To: gentoo-dev@lists.gentoo.org Subject: Re: [gentoo-dev] GLEP 42 "Critical News Reporting" Round Two Message-ID: <20051105173426.1ce20468@snowdrop.home> In-Reply-To: <436C8951.4010008@gentoo.org> References: <20051105005814.0de0d8ff@snowdrop.home> <436C8951.4010008@gentoo.org> X-Mailer: Sylpheed-Claws 1.9.99-rc2 (GTK+ 2.6.10; i686-pc-linux-gnu) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Reply-to: gentoo-dev@lists.gentoo.org Mime-Version: 1.0 Content-Type: multipart/signed; boundary=Signature_Sat__5_Nov_2005_17_34_26_+0000_aJkgIxyw0ffdu0VG; protocol="application/pgp-signature"; micalg=PGP-SHA1 X-Archives-Salt: 1ad6c4b2-c1a2-4faa-8d23-00126f0ffde6 X-Archives-Hash: 1b892bb561a0825eddfaee58edc7fd45 --Signature_Sat__5_Nov_2005_17_34_26_+0000_aJkgIxyw0ffdu0VG Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable On Sat, 05 Nov 2005 11:28:33 +0100 Grobian wrote: | > Preemptive | > Users should be told of changes *before* they break the user's | > system, after the damage has already been done. |=20 | style suggestion for unambigous interpretation: | perhaps a "because if applied afterwards" instead of "after" Ugh. Wonder how many comments I'm going to get on that one... There should be a "not" before "system", which I accidentally killed by pressing the wrong key in Vim. | Apart from that this point seems to repeat much of the previous one, | it introduces a new unfounded claim (users do read, but now too late) Read the linked forums thread and all will become clear. | > Lightweight | > It is not reasonable to expect all users to have an MTA, web | > browser, email client, cron daemon or text processing suite | > available on their system. |=20 | Direct question that follows from this: what *do* we expect a=20 | user/system to have available? I think it's good to state that as | well, since you're excluding a lot here in once sentence. Anything that's in the system target, and as little as is reasonably possible extra. | Where does point 4 differ from the second part of point 3? Oops. | > 6. Portage filters the news item and, if it is relevant, installs | > it in a special location to be read by a news item reader. Messages | > are also displayed to inform the user that news is available. |=20 | So, same as for point 5, the exact details on how this works and what | a 'news item reader' is (since you previously defined a requirement | of having almost nothing available on the system) should be refered | to here. I want to be sure that you will elaborate on it lateron, so | I can stack up my many questions for now. A news item reader is something which reads news items. | > The news item will be named in the form | > ``yyyy-mm-dd-item-name.en.txt``, where ``item-name`` is a very | > short name (e.g. ``apache-updates``) and ``en`` is the two letter | > ISO 639 [#iso-639]_ language code for the news item. The short name | > must consist only of characters ``a-z``, ``A-Z``, ``0-9`` and ``-`` | > (hyphen). |=20 | Consider replacing hyphen with an underscore to ease parsing. Mixing hyphens and underscores? That's just going to start confusing things... | (Maybe: "An English (''en'') version must be available for all news=20 | items as per GLEP 34 [#glep-34]_. Other languages ...") GLEP 34 doesn't say anything about news items... | > ``Author:`` | > Author's name and email address, in the form ``Real Name | > ``. Mandatory, multiple author fields may be | > specified if appropriate. |=20 | Separated how? Using commas, semicolons, spaces or whatever? Multiple fields. Maybe that'd be clearer were it to say "Mandatory; multiple author headers may ...". | > ``Version:`` | > Initially 1. Incremented every time a non-trivial change is | > made. Changes which require a re-read of the news item should | > instead use a new news item file. |=20 | Perhaps you want to track trivial changes as well in the minor, in | order to be able to quickly see a change was made, and prevent people | from considering a non-trivial change as trivial. Well, if you want to see that it was made, it's not trivial. | Maybe you should explicitly state this field is optional and why. I | could think of some reasons why this header should be mandatory, but | perhaps you add a completely different value to the header than I do | now. Maybe I should just mark it as mandatory instead. | From a completeness perspective, it would perhaps be a option to=20 | include a special header that contains a boolean expression that=20 | resolves to true if the message is relevant to the user, and false=20 | otherwise. This would allow AND and NOT to be included instead of | only OR semantics. | | In any case, elaborate on why supporting only OR was chosen and why=20 | other (probably investigated) options were discarded (and hence make | my statement above unnecessary). The previous draft had an option for and or none-of modes. I took it out because I don't think it's going to be anywhere near as useful as one might initially think. | > The text body should be wrapped at 72 characters. No fancy | > formatting or tab characters should be used -- the news item may be | > being displayed directly to a terminal. Paragraphs should be | > separated by two blank lines. |=20 | Elaborate some more on "No fancy formatting or tab characters". | People might want/like to include a bulleted/numbered list or insert | a small (shell) code example. Also make some note on the average | length (number of paragraphs) and perhaps a predefined structure | (ie.: introduction/abstract, impact, solutions/actions, | links/more-information) These're things to be decided when news items are sent for review. Once we have some real material there'll be a more useful way of judging what is acceptable and what has gone too far. | > Thus, all proposed news items must be posted to the ``gentoo-dev`` | > or ``gentoo-core`` mailing list, and ``Cc:``\ed to | > ``pr@gentoo.org`` at least 72 hours before being committed | > (exceptions may be made in exceptional circumstances). Any | > complaints regarding wording or clarity **must** be addressed | > before the news item goes live. |=20 | The idea is great, but perhaps the current docs teams should deal | with this, as they are currently responsible for the webpages as well? There's nothing saying "don't Cc: the docs people". By all means Cc: them if they are relevant... | In any case: | - 72 hours is a lot (is there a way to shorten it when everything is | there?) For a major change? If you don't have a major change planned out at least 72 hours in advance you shouldn't be making it. | - what if noone feels like commenting on the submission? Then it's assumed correct. | - how do you know a certain dev is a competent English speaker? *shrug* If we ever get onto linguistics arguments, there're enough of us with copies of Fowler and the OUP Style Guide to settle things. | This raises many questions. I suggest to define the process a bit | more and include a scheme that deals with this kind of concerns to | actually make it water (and fool) proof. Pfff, no system is fool proof. All adding more tricky little items will do is piss people off. | > News items must only be for **important** changes that may cause | > serious upgrade or compatibility problems. Ordinary upgrade | > messages and non-critical news items should remain in ``einfo`` | > notices. The importance of the message to its intended audience | > should be justified with the proposal. |=20 | Somehow there needs to be a voting/selection process to figure out=20 | whether something is **important** or not.=20 It's important if you can justify it as such on -dev. | Does portage only 'warn' and still continue, or does it completely | stop when an unread news item is found for a package that is to be | upgraded? In the first case, the 'preemptive' requirement is being | violated, in the latter, the option for a '--force' or something must | be discussed. (Users with multiple systems might already know the | message, or users might not be interested in it since they don't run | the application in production.) Portage only *warns* you if you try to unmerge glibc... | This Section is too short in this form to live on its own. It should=20 | either be extended or merged with text above where I made a comment | on the details. Perhaps you can elaborate on how to implement such=20 | forwarders, especially in the light of my comments on the previous | Section. See "Reference Implementation". | This sounds much alike what 'mail' used to (and still) does. It has | the ability to see which messages are waiting, select them to read | with a pager and delete them. Make sure you explain why this is | better, and why you 'seemingly' reinvent the wheel here. I think I | can think of some reasons, but I think you need to make it clear. It's vaguely like mail, but without the MTA requirement. | Yes, and make it a requirement that all news messages get posted=20 | somewhere on public channels. I don't see any particular need to *require* that all news items are posted to a specific place. | I hope I have not created a new opportunity for large flame wars. I=20 | tried being quite constructive, and reviewed the GLEP as a scientific=20 | paper. It's a technical paper rather than a scientific one, so I'm not bothering to justify things that every developer should already know. It's mostly a question of space... I *could* bog everyone down in twenty pages of references, but why bother? --=20 Ciaran McCreesh : Gentoo Developer (Anti-XML, anti-newbie conspiracy) Mail : ciaranm at gentoo.org Web : http://dev.gentoo.org/~ciaranm --Signature_Sat__5_Nov_2005_17_34_26_+0000_aJkgIxyw0ffdu0VG Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.1 (GNU/Linux) iD8DBQFDbO0k96zL6DUtXhERAmgyAKCv9PPPdOmnUYDAaXrrZz4J9AvgUwCfXSka 8ipC3BW/WTWRNn6CCKHMdJw= =2sz3 -----END PGP SIGNATURE----- --Signature_Sat__5_Nov_2005_17_34_26_+0000_aJkgIxyw0ffdu0VG-- -- gentoo-dev@gentoo.org mailing list