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 1EYLKM-0003ly-R4 for garchives@archives.gentoo.org; Sat, 05 Nov 2005 10:31:15 +0000 Received: from robin.gentoo.org (localhost [127.0.0.1]) by robin.gentoo.org (8.13.5/8.13.5) with SMTP id jA5AUWsV013104; Sat, 5 Nov 2005 10:30:32 GMT Received: from hermes.orakel.ods.org (dsl67-66.fastxdsl.nl [62.251.66.67]) by robin.gentoo.org (8.13.5/8.13.5) with ESMTP id jA5ASgtx029300 for ; Sat, 5 Nov 2005 10:28:42 GMT Received: from aphrodite.orakel.ods.org ([172.17.2.15]) by hermes.orakel.ods.org with esmtps (TLSv1:AES256-SHA:256) (Exim 4.54) id 1EYLHl-0006Sp-V0 for gentoo-dev@lists.gentoo.org; Sat, 05 Nov 2005 11:28:37 +0100 Message-ID: <436C8951.4010008@gentoo.org> Date: Sat, 05 Nov 2005 11:28:33 +0100 From: Grobian Organization: Gentoo Foundation User-Agent: Thunderbird 1.4.1 (Macintosh/20051006) 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 To: gentoo-dev@lists.gentoo.org Subject: Re: [gentoo-dev] GLEP 42 "Critical News Reporting" Round Two References: <20051105005814.0de0d8ff@snowdrop.home> In-Reply-To: <20051105005814.0de0d8ff@snowdrop.home> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Content-Scanned: by hermes.orakel.ods.org (Exim Exiscan) using SpamAssassin and ClamAV X-Archives-Salt: 6a4757de-11fe-4e34-8e90-ba8895e01c83 X-Archives-Hash: 30a4fb93d21b32bbe7d6fe379763ddb4 Ciaran McCreesh wrote: > Motivation > ========== > > There are currently several ways of getting news out to our users, none of them > particularly effective: This assumes the following ways are really ineffective, something which you don't prove or give any reason for. Hence it's eligable for another big discussion. To avoid that, I would suggest to add a number of reasons, or whatever to make this assumption sound (more) valid. It is important, I think, that the reader can understand your grounds for saying this. (I personally disagree on this statement now, but it makes no use discussing it since you haven't given any ground as on why. Maybe if you would give a definition, I could adjust my own definition and agree.) > A more reliable way of getting news of critical updates out to users is required > to avoid repeats of the various recent upgrade debacles. Perhaps you want to add a small footnote here, to give a small example of such debacle, and using that example point out what is the problem you think is important, and hence will address in this paper... eh GLEP. > This GLEP proposes a > solution based around pushing news items out to the user via the ``rsync`` tree. This is a minor side issue, but I think that GLEP 2 states that you should use ' instead of `. No discussion on it please, I might be wrong or you just didn't know. > Preemptive > Users should be told of changes *before* they break the user's system, > after the damage has already been done. style suggestion for unambigous interpretation: perhaps a "because if applied afterwards" instead of "after" > No user subscription required > It has already been demonstrated [#forums-whining]_ that many users do not > read the ``gentoo-announce`` mailing list or ``RSS`` feeds. A solution which > requires subscription has no advantage over current methods. You implicitly state that many users do not read the gentoo-announce list and RSS-feeds because they are subscription based. This sounds like a too quick assumption to me. At least it is not founded in any way. Consider that for RSS-feeds one typically doesn't have to subscribe, but just add it to his/her reader. Make clear why you think the subscription model stops users from reading, and why a push-based alternative (as you suggest here) will work. Remember that it is easy to say here that users don't read what's on their consoles as well, as in post emerge messages etc. So make sure you deal with it upfront, why you think now it *will* work. > No user monitoring required > It has already been demonstrated [#forums-whining]_ that many users do not > read news items posted to the Gentoo website, or do not read news items > until it is too late. A solution that relies upon active monitoring of a > particular source has no advantage over current methods. 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) which somehow contradicts previous statements. Beware that you clearly deal with this, or just introduce it earlier so it doesn't look you're contradicting yourself. > 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. Direct question that follows from this: what *do* we expect a 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. > 3. The news item is committed to a CVS (or Subversion [#glep-36]_) repository. > From here, it is merged with the rsync tree. This is described in `News Item > Distribution`_. > 4. The news item is merged with the rsync tree. Implementation details of this > point are beyond the scope of this GLEP; existing solutions are in place > for merging GLSAs to the tree. Where does point 4 differ from the second part of point 3? Also, point 3 implies that the merging into the rsync tree is being described further on, while point 4 states the oposite of not discussing it (out of scope). Maybe split point 3 and merge with 4? > 5. Users fetch the news item when they sync. This ensures that the news items in > question are pushed to the user before the user accidentally makes an > unwanted change. No changes to the existing rsync process are required by > this GLEP. I would suggest a reference to a place where you will explain this 'pushing' to the user in detail. Especially the time and the way how are important. Or maybe I was just confused by "pushed" and is the only thing this point wants to say that all news items are just synced together with the rest of the portage tree upon a emerge --sync. The latter sounds logical considering the last sentence quoted above. > 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. 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. > 7. The news item is handled by the user's choice of news item reader. See `News > Item Clients`_. Wow. Seems like point 6 mentioned 'news item reader' too early! Same for point 5 of mentioning "pushing" which is only dealt with in point 6. In any case, the reference is there: good. > 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). Consider replacing hyphen with an underscore to ease parsing. > An English (``en``) version must be available for all news items. Other > languages may be provided either by the original author or by other translators > who have commit access. This anglocentricity is justified on the grounds that > nobody objected to it with GLEP 34 [#glep-34]_. This might sound a bit 'attacking'. Try to rephrase it a bit to sound more formal. Also, note that probably noone cares about it and takes it for granted. You included support for other languages, so there's nothing to make a sharp point on here, I guess. (Maybe: "An English (''en'') version must be available for all news items as per GLEP 34 [#glep-34]_. Other languages ...") > A news item's content will consist of an RFC 822 [#rfc-822]_ style header > followed by the main body of the message as plain text. This GLEP defines > various optional and mandatory headers. Future GLEPs may propose new headers -- > tools handling these news items must ignore any unrecognised header. Ah, a clear sight on the future. Good! (Also from the perspective of the paper.) > ``Author:`` > Author's name and email address, in the form ``Real Name ``. > Mandatory, multiple author fields may be specified if appropriate. Separated how? Using commas, semicolons, spaces or whatever? > ``Posted:`` > Date of posting, in ``dd-mmm-yyyy`` format (e.g. 14-Aug-2001). UTC time in > ``hh-mm-ss +0000`` format may also be included. This field is mandatory. Consider stressing the requirement for UTC time by stating it in a separate sentence. > ``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. 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. 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. > The following headers are used for filtering. If none of these headers are > specified, the news item is displayed for all users. Otherwise, the news item is > displayed if *at least one* header matches. From a completeness perspective, it would perhaps be a option to include a special header that contains a boolean expression that resolves to true if the message is relevant to the user, and false 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 other (probably investigated) options were discarded (and hence make my statement above unnecessary). > 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. 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) > YourSQL databases created using YourSQL version 4.0 are incompatible > with YourSQL version 4.1 or later. There is no reliable way to > automate the database format conversion, so action from the system > administrator is required before an upgrade can take place. > > Please see the Gentoo YourSQL Upgrade Guide for instructions: > > http://www.gentoo.org/doc/en/yoursql-upgrading.xml Note that this indenting of the URL can be considered 'fancy formatting'. Hence there is a clear need to define the term. > > Also see the official YourSQL documentation: > > http://dev.yoursql.com/doc/refman/4.1/en/upgrading-from-4-0.html > > After upgrading, you should also recompile any packages which link > against YourSQL: > > revdep-rebuild --library=libyoursqlclient.so.12 > > The revdep-rebuild tool is provided by app-portage/gentoolkit. Consider including a new paragraph in the example just to show your proposed structure. > 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. The idea is great, but perhaps the current docs teams should deal with this, as they are currently responsible for the webpages as well? In any case: - 72 hours is a lot (is there a way to shorten it when everything is there?) - consider using either -dev or -core not both in an "OR" relation, clarity if good for everyone. - what if noone feels like commenting on the submission? - how do you know a certain dev is a competent English speaker? - when do you know that it has been read, approved? 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. > 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. Somehow there needs to be a voting/selection process to figure out whether something is **important** or not. Be aware that there are bugs that indicate that users would like to see all einfo messages being delivered to them in some way. It might be confusing to the user what is the difference (and for me as well... when is something considered important?). Try to define what you think is important, or maybe give some well explanatory examples and what the advantage is over einfo. To comment on your YourSQL example: perhaps YourSQL just gives an error about an incompatible database when starting it, and points itself to a migration site. One could consider for this reason a message on it not important, as nothing gets unrepairable broken. Linking back to your 'preemptive' requirement: define damage and broken. > The unread news message will also be displayed immediately after an > ``emerge sync``. Include a note on configurability, i.e. disabling such behaviour for users that don't like it. Elaborating on other ways to inform the administrator (ie. via email) would be great too. Consider automated installs, end-user/desktop installs (basically everything from big to small) such that for each situation the information being supplied can be pushed to the admin in the way that is desirable (for him/her). > Portage may also warn of unread news items using, for example, a red flashy > before actions such as merging a package. > > Portage must keep track of news items which have already been installed to avoid > repeatedly reinstalling a deleted news item. > > Users who really don't care about news items can use ``rsync_excludes`` to > filter out the ``news/`` directory. 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.) A concluding note on this Section is that I have the impression that only one use-scenario has been dealt with. Both this scenario is not described, as well as that this scenario doesn't reflect 99.9% of our user base. Many alternative opinions will stem from the fact that different people envision different scenarios. I think that elaborating on a number of representative (need not to be most popular) scenarios and how the proposed setup functions in there is good to get a grip on the many different demands of users. I could help to define a scenario for a larger scale more or less automated/cronned install. > News Item Clients > ----------------- > > Once a news item is 'installed', third party tools (or a traditional Unix pager > and ``rm``) can be used to display and view the news files. An ``eselect`` > [#eselect]_ module shall be created as the 'suggested' display tool; other > display tools (for example, a news to email forwarder, which would be ideal for > users who sync on a cron) are left as options for those who desire them -- the > simple file format make this relatively simple. This Section is too short in this form to live on its own. It should 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 forwarders, especially in the light of my comments on the previous Section. > News Item Removal > ----------------- > > News items can be removed (by removing the news file from the main tree) when > they are no longer relevant, if they are made obsolete by a future news item or > after a long period of time. This is the same as the method used for ``updates`` > entries. 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. > Integration with Existing Systems > ================================= > > It would be trivial to convert these news items into the format used for news > items on the Gentoo website or posts for the ``gentoo-announce`` mailing list. Yes, and make it a requirement that all news messages get posted somewhere on public channels. Some admins really like to see all news items, so your GLEP should cover the possibility for that, I think. Somewhat related to my suggestion for using scenarios, this also implies that there will be users that want to turn this off completely, as such doing the right rsync_exclude should be documented somewhere. I hope I have not created a new opportunity for large flame wars. I tried being quite constructive, and reviewed the GLEP as a scientific paper. Given the fact I had a lot to add, indicates for me there are a lot of questions to be asked regarding this GLEP. Many of those questions can simply be answered by providing the underlying rationales and background information that is not made explicit. I hope you can do something useful with my comments. If you don't like them, ignore them and throw them away. If you want to use them, feel free to do so. -- Fabian Groffen Gentoo for Mac OS X Project -- Interim Lead -- gentoo-dev@gentoo.org mailing list