| Summary: | GLEP 42: Define support for EAPI 5 dependency atoms in news items | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Mike Gilbert <floppym> |
| Component: | GLEP Changes | Assignee: | GLEP Editors <glep> |
| Status: | RESOLVED FIXED | ||
| Severity: | normal | CC: | chithanh, council, pms, zmedico |
| Priority: | Normal | ||
| Version: | unspecified | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Whiteboard: | |||
| Package list: | Runtime testing required: | --- | |
| Attachments: |
Proposed change
Proposed change to GLEP 42 |
||
Since this does change the content of the GLEP, I'd prefer that the Council sign off before making the change. Created attachment 419948 [details, diff]
Proposed change to GLEP 42
Following discussing in the 2015-12-13 council meeting, here is an updated patch.
- Define News-Item-Format 1.1. It uses EAPI 5 for dependencies.
- Clarify that format 1.0 uses EAPI 0.
- Replace the term "dependency atom" by "package dependency specification"
(which is the term used by PMS).
- Update the two package examples (since they are horribly outdated).
- Add a reference to the PMS document.
(In reply to Ulrich Müller from comment #2) > Created attachment 419948 [details, diff] [details, diff] > Proposed change to GLEP 42 This has been approved in the 2016-01-10 council meeting. Sorry I am late to the party, but this change is not backwards compatible, is it? I think the major version needs to be incremented, if the loss of backwards compatibility is intentional. Or some identifier different from "Display-If-Installed" has to be used, then the new format will be backwards compatible. (In reply to Chí-Thanh Christopher Nguyễn from comment #4) > Sorry I am late to the party, but this change is not backwards compatible, > is it? EAPI 0 dependency specifications are a subset of the EAPI 5 ones. So the change should be backward compatible. (It isn't forward compatible but that's not required.) This is not how I understand backwards compatibility. The new format, if it increases the minor version only, should be backwards compatible with old GLEP 42 readers who don't understand EAPI 5 dependency specifications and/or expect only dependency atoms in Display-If-Installed. (In reply to Chí-Thanh Christopher Nguyễn from comment #6) > The new format, if it increases the minor version only, should be backwards > compatible with old GLEP 42 readers who don't understand EAPI 5 dependency > specifications and/or expect only dependency atoms in Display-If-Installed. As I understand it: Backward compatibility = 1.1 readers understand 1.0 data Forward compatibility = 1.0 readers understand 1.1 data ulm's definition of "backward compatibility" seems correct to me. As I understand it, the purpose of the News-Item-Format field is to be used by the reader to determine whether the news item can be displayed/processed or not. If the reader is 1.0 compatible, it can expect to get meaningful (possibly gracefully degraded) results from parsing 1.1, 1.2, etc. formats while treating them as 1.0. Only if the reader sees an item in 2.0 or greater format, then it cannot parse and must ignore it. (In reply to Chí-Thanh Christopher Nguyễn from comment #9) That understanding seems incorrect to me. Err... I guess that definition does make more sense. Otherwise, as you say, we break readers with every minor version bump, which is silly. So yeah, I think it would be more appropriate to make this 2.0 instead. We won't break any news readers as both portage and paludis explicitly check for format 1.0 (as it should be): https://gitweb.gentoo.org/proj/portage.git/tree/pym/portage/news.py#n273 http://git.exherbo.org/paludis/paludis.git/tree/paludis/repositories/e/e_repository_news.cc#n326 AFAICS, pkgcore doesn't include any code for news items. Finally, the eselect reader doesn't care about the "Display-If-Installed" header (because it is processed by the package manager). From <https://en.wikipedia.org/wiki/Backward_compatibility>: In telecommunications and computing, a product or technology is backward compatible (BC)[1] or downward compatible if it can function properly given input generated by, or meant for, an older product or technology, such as a legacy system.[2] If products designed for the new standard can receive, read, view or play older standards or formats, then the product is said to be backward-compatible; examples of such a standard include data formats and communication protocols. Modifications to a system that do not allow backward compatibility are sometimes called "breaking changes." The reverse is forward compatibility, which implies that old devices allow (or are expected to allow) data formats generated by new (or future) devices, perhaps without supporting all new features. A standard supports forward compatibility if older product versions can receive, read, view or play the new standard. The former is precisely the situation that we have here. We could of course go with format 2.0 but then we should change the GLEP to say "forward compatible" instead of "backward compatible". Which I fear would require another council decision. (In reply to Ulrich Müller from comment #12) > We won't break any news readers as both portage and paludis explicitly check > for format 1.0 (as it should be): By "break", I meant that the reader is unable or refuses to display some subset of news items. Anyway, if we want to clarify/change the meaning of minor version numbers in a news item context, that probably deserves another bug. (In reply to Mike Gilbert from comment #14) > > We won't break any news readers as both portage and paludis explicitly check > > for format 1.0 (as it should be): > > By "break", I meant that the reader is unable or refuses to display some > subset of news items. Current package managers will refuse anything but format 1.0, so in this respect it doesn't make any difference if we call the new format 1.1 or 2.0. I skimmed through the discussion of GLEP 42 in 2005, and the only message I could find about the format header is this one: https://archives.gentoo.org/gentoo-dev/message/d30de011db9067ae3cc298de2b4ee1b2 One could argue that what was meant there are forwards-compatible changes and that the GLEP should say so. (In fact, the distinction between major and minor version doesn't make any sense if readers accept only an exact version like 1.0.) > Anyway, if we want to clarify/change the meaning of minor version numbers in > a news item context, that probably deserves another bug. Not sure if splitting the discussion would be helpful. Adding council back to CC. I would prefer to stay out of any further debate about the version number. I am happy with whatever will get me the originally requested feature in a timely manner. The intention was that you'd use 2.0 if you introduced anything which would result in incorrect behaviour in older clients. So 1.1 could add new headers that could safely be ignored, for example (maybe a Display-In-Bright-Pink: true), but not headers that would result in incorrect behaviour, which EAPI changes would. I think the confusion here is whether we're talking about the file formats being backwards compatible, or the programs. For the file format to be backwards compatible, it must avoid breaking any older program. (In reply to Ciaran McCreesh from comment #17) Thanks for clarifying. > I think the confusion here is whether we're talking about the file formats > being backwards compatible, or the programs. For the file format to be > backwards compatible, it must avoid breaking any older program. Apparently the wording of the GLEP could profit from some improvement there, to avoid such confusion in future. An updated version of GLEP 42 is in my user space on the wiki: https://wiki.gentoo.org/wiki/User:Ulm/GLEP:42 The relevant change for news item format 2.0 is here: https://wiki.gentoo.org/index.php?title=User%3AUlm%2FGLEP%3A42&type=revision&diff=467060&oldid=467058 (In reply to Ulrich Müller from comment #19) > An updated version of GLEP 42 is in my user space on the wiki: > https://wiki.gentoo.org/wiki/User:Ulm/GLEP:42 This has been approved in today's council meeting: https://projects.gentoo.org/council/meeting-logs/20160313.txt Changes added. |
Created attachment 419038 [details, diff] Proposed change GLEP 42 should be modified to explicitly support EAPI 5 dependency atom syntax in news items. I have attached a small patch which updates the existing text, defining news item format 1.1. If this should instead be added under a new section, please suggest a location for it.