Draft a version of the metadata specification

[Olf0]

Preface

The original SailfishOS:Chum metadata specification (version 0) for packages in the SailfishOS:Chum community repository is well designed and works fine. Still, after using it for 1,5 years and overhauling it a year ago, I perceived four flaws, which I pondered about every now and then. I took my time to come up with something comprehensive and to reduce the likeliness to suggest nonsense.

Motivation

Cease confusing developers, rpmlint and syntax-highlighting editors by using words in the tags for SailfishOS:Chum metadata, which already can be used for other purposes / RPM tags in a spec file: "Icon", "URL" and "Name" of a package.

Assessments

The Icon: tag

• The Icon: tag collides with the Icon: tag defined by RPM for spec files. While it is rarely used today (I experimented with it in sfos-upgrade etc. years ago), as it only allows for a XPM or GIF file, rpmlint complains about its use in the %description section (correctly stating that it is misplaced there); to which extent depends on the rpmlint version and configuration.
  Side notes: RPM's Icon: tag was supposed to be displayed in graphical package manager front-ends, which is a equivalent purpose it has in the SailfishOS:Chum metadata. But as it still works with current RPM releases, a collision definitely exists, only alleviated by the fact that the %description section is basically a free text field.
• Syntax-highlighting editors also detect and display the Icon: tag as part of the regular RPM spec file syntax.
• For long time users of RPM it is confusing (as for rpmlint) that a well known tag is reused in a different context with different properties.
• Linguistically it is rather a project's "logo" which is displayed, as "icon" in information technology today most often addresses a desktop icon. Specifically the icon for the SailfishOS launcher may be a different one than the icon / logo used for SailfishOS:Chum's metadata, hence it should be named differently to avoid any confusion.

Thus Icon: tag in the SailfishOS:Chum metadata specification is renamed to Logo: PackageIcon.

The Url: tag

• The Url: tag slightly collides with the URL: tag defined by RPM for spec files. While current versions of rpmlint do not complain about its use in the %description section, presumably due to the different capitalisation, older versions do (also stating that it is misplaced there, as with Icon:).
• Aside of the technical aspects it is really confusing for developers to handle two tags which solely differ in their capitalisation. I have already seen it spelled "URL:" for SailfishOS:Chum's metadata and then all versions of rpmlint certainly do complain about its use in the %description section.
• The spelling "Url" is … well, "uncommon": I have not seen it before.
• Syntax-highlighting editors also detect and display the Url: tag as part of the regular RPM spec file syntax, despite its different capitalisation.
• Linguistically it is a list of "URLs" / "Links" which follows this tag (which may comprise only a single element) in contrast to a single "URL", which follows RPM's URL: tag.

Thus the Url: tag in the SailfishOS:Chum metadata specification is renamed to URLs: or Links:.

The PackageName: tag

• Even though no technical conflict exists for this tag, linguistically "package name" in the context of RPM and its spec files always addresses the value of RPM's Name: tag (i.e., %{name}). This is confusing, because the two are not related, even though they may be set alike by PackageName: %{name}, but …
• PackageName: clearly has different properties than the classic "package name" (%{name}): In can be a line of text comprising multiple words, in stark contrast to the RPM's Name: tag (the real "package name"). This is confusing. While PackageName: may be used for a short description, this is not its intended use AFAIU, and "description" is another word which shall be avoided in the context of RPM and its spec files due to the prevalent %description section; the same applies to "summary" due to RPM's Summary: tag. "Package title" best describes the intended use of PackageName: and the fact that it can be a line comprising multiple words.
• The SailfishOS:Chum GUI app itself displays the real RPM package name prefixed by the string "Package name:" in the AppInformation block.
• PackageName: only deviates in a single letter from the tag PackagerName:, making both of them easy to misread or mistype.

Thus the PackageName: tag in the SailfishOS:Chum metadata specification is renamed to PackageTitle: or simply Title:.

Lacking versioning

• Currently SailfishOS:Chum's metadata specification lacks versioning. Any proper specification must include versioning, because without versioning it is impossible to address a specific state of the specification in terms of time and content, both technically and for discussing the specification or any aspect (e.g., here: tag) of it.
• To enable tracking any changes of a specification (for humans and by technical measures), versioning is necessary. For introducing disruptive changes, versioning is a prerequisite.
• Semantic versioning is the way to go today. I.e., any version must conform to the ERE ^[0-9]+\.[0-9]+\.[0-9]+$.
• To make the version evaluation as easy as possible, the software only has to evaluate the first digit for disruptive ("breaking") changes, i.e., deprecated tags becoming invalid.
• Changes in the minor release version indicate new tags added, either as synonyms to extant ones or as completely new tags.
• Changes to the point version indicate that tag definitions have been slightly altered, in the classic sense of a bug fix.
• As the current version is described as the first beta version (it is definitely not in alpha state any more) and has undergone a few revisions, I suppose it is at some 0.1.x. Hence a version incorporating these changes described here would be appropriately named 0.2.0. Side note: AFAIU the SailfishOS:Chum metadata specification is never supposed to reach 1.0.0, because it should be superseded by something "proper / better" (i.e., to always stay in beta state); but IMO it is basically fine and I suspect it might turn out to be a permanent measure.

Thus a new tag ChumVersion: is introduced. Its value must conform to ^[0-9]+[0-9]+[0-9]+$. The initial value for this revision of the SailfishOS:Chum metadata specification is 0.2.0. Any SailfishOS:Chum metadata without a ChumVersion: tag will be treated as adhering to the original SailfishOS:Chum metadata specification, as if the ChumVersion: tag is set to 0.1.0.

The original SailfishOS:Chum metadata definition is called "version 0", the one which introduces these four new tags is called "version 1". Due to its informal nature it is called "SailfishOS:Chum metadata definition", not "metadata specification".

Migration

• As usual which breaking specification changes, we as the specification writers shall communicate the deprecation clearly but handle it in a relaxed manner. The suggested new version is designed to primarily to increase clarity for human writers and readers by avoiding confusing and confusingly similar tags and terms. Plus silence rpmlint and prevent editors from highlighting RPM keywords incorrectly, which both further contributes to confusing developers. Currently no necessity exists to invalidate tags defined in the original version of the SailfishOS:Chum metadata specification, only aforementioned three tags become deprecated with the release of this specification.
• Because the SailfishOS:Chum metadata specification is managed by Git, all old versions are accessible. BTW, I suggested a measure to decouple the Git tags for the SailfishOS:Chum metadata specification from the ones of the SailfishOS:Chum repository configuration RPM(s) in issue #99.

Implementation

@nephros implemented these changes in the source code of the SailfishOS:Chum GUI application (no need to rush executing this, primarily I would like to receive an "O.K."), so I created a pull request for the SailfishOS:Chum metadata specification with these changes, which can be reviewed. I also suggest to make obvious in the source code, which tags are the deprecated ones and which are the current ones, either by comments or coding (edit: well done by @nephros).

[rinigus]

Good points regarding the changes. Would have to think a bit on proposed names.

In general, I don't like that rpmlint checks free text field and complains about it. But, it is not up to us to change that.

Re implementation: I wouldn't mind implementing it - should be simple to do so. So, it wouldn't be hanging too long on that as soon as we agree on what to change.

[Olf0]

Would have to think a bit on proposed names.

Please do so! My suggestions are the best words for these tags which came to my mind by thinking about them many times in the past ~ 10 months. This is also why I provided extensive reasoning, including words which should be definitely avoided IMO.

I know this is easy to implement; if it would be C code, I might have offered to do that and leave the quality assurance to you (either singular or plural). But the important point is the get the specification right, first! And the main criterion is not so so much if they sound right to a native speaker (e.g., @piggz) or someone who as written and quality assured technical specifications in an international IT-industry association for many years (me), but if they constitute an improvement for the average developer (and rpmlint).

[Olf0]

Change

I clarified, that the new tags are only valid if ChumVersion: is set to 0.2.0 or greater; the superseded tags are then invalid and must not be evaluated. Vice versa, if ChumVersion: is not set (equivalent to 0.1.x), the tags introduced with version 0.2.0 are still invalid and must not be evaluated.

[rinigus]

With the change of a spec we would have to define a target. In particular, you mentioned that we shouldn't care much about rpmlint, but mainly focus on developer. From developer POV, the most that I dislike is a change in specs for no reason. I probably have selective memory, but I don't remember much complains regarding used tags. As it is, we get new applications in Chum and they seem to be all doing fine. But I can be mistaken...

So, if we don't care about rpmlint, maybe we should live happily with what we have. Note that if rpmlint is very much bugging, maybe it is possible to disable some checks for OBS project. Although, I am not sure.

So, before proceeding, maybe we should define a target and see if we want to go there. I am inclined on keeping it as it is just to avoid extra work of all package maintainers that is involved.

PS: Just looked - we are already at 261 packages!

[Olf0]

With the change of a spec we would have to define a target.

Yes, assuming "target" means "aim" or "goal". I thought this becomes obvious by reading the first posting here: To stop confusing developers, rpmlint and syntax-highlighting editors by using words in the tags for SailfishOS:Chum metadata, which are already used for other purposes in the spec file: "Icon", "URL" and "Name" of a package.

BTW, I forgot to mention that syntax-highlighting editors also detect "Icon:" and "Url:" as reserved keywords of an RPM spec file in contrast to all other tags of the SailfishOS:Chum metadata specification. I have seen that with KDE's Kate, GitHub's web-editor and GitHub's IDE editor (these are the only ones I use besides vi / vim for which I have not turned on the syntax-highlighting).

In particular, you mentioned that we shouldn't care much about rpmlint, but mainly focus on developer.

No, AFAICS I did not write anything like that: From my perspective, both shall not be(come) confused, plus syntax-highlighting editors, which in turn also confuse developers by highlighting these as RPM tags.

I probably have selective memory, but I don't remember much complains regarding used tags. As it is, we get new applications in Chum and they seem to be all doing fine. But I can be mistaken...

IMO, you are and you are not at the same time:

• I was confused by all three points and reread the spec multiple times to get it right. Actually that was the reason why I clarified the descriptions of the tags about a year ago. At that time I did not dare to suggest changing the tags, because I felt that I had not thought about potential changes thoroughly enough; hence my approach back then was to that limit the changes to the tag descriptions.
  This and a few tests also made me understand that the PackageName: is a free text field suitable for any title or very short description of a package.
• Most people do set the PackageName: to the real "package name" %{name} or a naturally spelled variant of it (as I did originally with "Storeman Installer"), likely because of <see last bullet point "In general: …" below>. But one may use %{summary} for it, which must be single line, too, or any other short line of text (e.g., now "Storeman Installer for SailfishOS").
• I received a contribution getting the SailfishOS:Chum metadata tags wrong.
• Ultimately everyone who tests properly will get it right, because one can easily check when a package is in SailfishOS:Chum:Testing, if this looks right in the SailfishOS:Chum GUI app.
• Actually the naming confusion has contributed to my misinterpretation that an "Icon:" is not displayed by the SailfishOS:Chum GUI app if a package is text mode / command line software. While these cannot have a (desktop / launcher) icon, many of them have a logo, e.g., sfos-upgrade. (I filed an incorrect issue report for this.)
• In general: Words have meanings, which creates images in ones mind (aka "notions", "mental images", "imaginations"). Badly chosen terms create wrong impressions, which might result in wrong interpretations and doing things incorrectly. Still, everybody who tests well, will find out and correct that. This is "extra work" in contrast to …

So, before proceeding, maybe we should define a target and see if we want to go there. I am inclined on keeping it as it is just to avoid extra work of all package maintainers that is involved.

PS: Just looked - we are already at 261 packages!

???
There is no "extra work for developers" at all, only for you to implement this and me changing the metadata specification. Every SailfishOS:Chum metadata configuration which adheres to the current specification 0.1.x will stay valid, despite 0.1.x being "deprecated". It is up to us, if we ever define 0.1.x as "invalid" and before a metadata specification 0.3.0 is released (which very likely will never happen), I see no reason to think about that.
Side note: I plan to write a new paragraph, in which all old specification versions are linked.

P.S. / slightly off topic:

Note that if rpmlint is very much bugging, maybe it is possible to disable some checks for OBS project. Although, I am not sure.

I once was "sure" that it "must" be able to silence all warnings and errors rpmlint emits by a correctly configured <package-name>.rmplintrc (or <package-name>-rmplintrc, both naming schemes work) file. A few hours later (!) I had determined that this works "a bit": I still have not understood, why I am able to silence some things and fail to suppress others. The only thing I know now, is that the two aforementioned file names are correct, any other name lets all errors and warnings emitted by rpmlint return.

Look, it is exactly such tedious detours which I want to avoid for other developers by writing above draft for a change. In would not have made the effort, if I am not convinced that it makes things easier for developers.

P.P.S.: Back on topic
Technically everything is working fine currently. Hence one can always argue, "there is not real necessity for such a change" or "this is just a superfluous beautification". But the current SailfishOS:Chum metadata specification is confusing rpmlint and syntax-highlighting editors, plus by that and some ambiguous terms chosen, lastly and likely the developers of packages for SailfishOS:Chum.

[rinigus]

OK, let's go through suggestions:

• Url -> Links: I guess should be OK. Better than playing with CaSe as it is now and what is expected to fix

• PackageName -> Title: fine by me

• Icon -> Logo is not very good. Logo could be something specific for a package and can lead to confusion as well. Any alternatives?

Versioning:

Two aspects. Iff we are going to use version tags, I would suggest to use 1, 2, and so on. No need for minor versions.

Addition of version tag would mean that we would require it in future, after version 1 deprecation having version specified. Not sure we want it. In principle, I would prefer to have minimal number of tags that are needed.

While not perfect, instead of enforcing a version, I would prefer to just add new tags as synonyms and use those in a mix as developer wishes.

[Olf0]

OK, let's go through suggestions:

I adapted the original text to the ones we agree upon.

• Icon -> Logo is not very good. Logo could be something specific for a package and can lead to confusion as well. Any alternatives?

Nothing I can think of (and I did that numerous times), but I can try to research this systematically by the help of a thesaurus (BTW, "image" is too generic and points in the direction of "picture"). But before I start doing that I need to understand, what you mean by "Logo could be something specific for a package …". Spontaneously I would have answered "But it is a specific logo for s specific software!", usually a project logo and maybe / often identical to the icon used for desktop, launcher etc.

Versioning:

Two aspects. If we are going to use version tags, I would suggest to use 1, 2, and so on. No need for minor versions.

Mmmh, I started to use semantic versioning long ago and each time I deviate from it, I regretted it sooner or later and returned to SemVer, hence I learned to stick to it in the first place. Here I considered point releases to be useful for non-breaking changes, i.e., the addition of new tags. And also, if the interpretation of tags is altered, for example, when implementing a change like issue #149.

But I do see the beauty of the simplicity of an single integer version number, which only covers changes of the tag syntax, hence this is O.K. for me. I adapted the document to it.

Addition of version tag would mean that we would require it in future, after version 1 deprecation having version specified. Not sure we want it.

As already stated: I do not expect a (now) version 3 to be(come) necessary. I also hope it will not. But I learnt to "never say never" many times. Circumstances we do not think of now may make that necessary.

In principle, I would prefer to have minimal number of tags that are needed.

I do concur with that as a guideline. But again, we both do not know what may be needed or wanted in the future. For example, if someone makes a nice contribution to the SailfishOS:Chum GUI app, which is introduces a new tag. I wholeheartedly believe and experienced many times, that one shall not assume to know for sure what the future brings. IMO, "surprises" and "unexpected changes" is a valid assumption for the future, at least in a long term perspective.

Aside from that, newly added tags (now) do not trigger a version change, only altering existing ones does.

While not perfect, instead of enforcing a version, I would prefer to just add new tags as synonyms and use those in a mix as developer wishes.

I initially considered such an approach, because it is the most simple way to implement and document these changes, i.e., for you and me. But:

• Having no specification version implicitly prevents to define a tag as invalid: That is impossible then.
• In think it is very awkward to have a specification without versioning. I wondered about that right from the start, but accepted a year ago, that the current metadata specification is just a preliminary measure which will soon be superseded by something better (that is even written in one of the markdown files of this project). But not having seen any step in this direction, I now believe that this will stay as the SailfishOS:Chum metadata specification, hence it should not be treated as a "quick & dirty" workaround any longer. This is exactly why I started this issue a few days ago: To advance the metadata definition to a proper specification. And also why I chose the title "Draft a version of the metadata specification", not "New tags to resolve technical and linguistic conflicts".
• To me the concept of "just add synonyms" instead of deprecating elements identified as problematic is just wrong. We may get away with it, if really no further changes become necessary in the future, which we cannot know now. Ultimately this appears to be a "quick & dirty" workaround instead of a proper fix.
• The same applies to the concept "anything goes" for packagers / app developers. Some will mix tags of different metadata versions, which will really result in confusion, if the need to invalidate a tag ever arises. Looks like quick shot to me, but nothing sustainable.
• The point "this is not a clean design" is basically the abstract gut feeling I have when I wrote the preceding points in this section, so it is rather a "meta point" than a concrete one.

Having thought about the topic versioning again while writing these points makes me want to insist on semantic versioning used properly: Start at 1.0.0, use the point release version (last field) for pure documentation changes (clarifications, corrections), the minor release version for non-breaking changes, which also affect code (slightly altering behaviour of existing tags, adding new tags etc.), and the major release version for breaking changes. The code would only have to evaluate the first digit (major release number), so you (mostly) get what you wanted.

[rinigus]

I have given it some thought and it would be good to get some thoughts from others regarding it. Right now, it seems that large part of motivation is coming from confusion caused by rpmlint and editors. However, when you read RPM SPEC file format docs, you would see that %description field is defined as

• %description is free form text, but there are two things to note. The first regards reformatting. Lines that begin with white space are considered “pre-formatted” and will be left alone. Adjacent lines without leading whitespace are considered a single paragraph and may be subject to formatting by glint or another RPM tool.

So, in principle, rpmlint and syntax highlighting have taken either lazy (highlighting, I presume) or overcautious approach (rpmlint?). In our case, the both are doing it wrong and I would even consider it as a bug of the software interpreting %description field in such manner.

If I remember correctly, PackageName was forced by rpmlint as we wanted to have just Name as a tag. Title wasn't proposed, I think. as we used AppData tags as a reference.

If we are going to change the tags, we will be still in the mercy of RPM SPEC staying the same. What if they will introduce Title? Or Logo? Chances are low, I admit, but we seem to be going down that rabbit hole.

In sum, I would like to hear opinion of others as well on the issue. Somehow we have to ask developers to read this discussion and voice their opinion.

More specific terms/discussion:

Logo could be something that is rather fixed and may not have a freedom of drawing something on the background, as some icons may do. They are not synonyms, but that is probably more important in corporate world. In this respect, icon would be correct to use as a tag in our spec.

Re versioning: we have rather small spec and number of developers using it. In this sense, I would still prefer using new tags as synonyms. In this we disagree.

[Olf0]

I have given it some thought and it would be good to get some thoughts from others regarding it.

Unfortunately I perceive this as backing out of your initially positive reaction, because this will likely stall this proposal for ever, which is equivalent to killing it. There is just too little interest, because in a way "it works". I also addressed @piggz right at the start, and now again.

I also do not see any drawbacks: This draft is an improvement, and very easy to implement. Most of the work is documentation, which I offered to perform. For me this is taking too long and becoming really tedious. As discussed elsewhere, I am about to wrap things up, so this either go or leave it. This discussion is eating much more time than implementing these changes takes.

Right now, it seems that large part of motivation is coming from confusion caused by rpmlint and editors. However, when you read RPM SPEC file format docs, you would see that ...

Rinigus, you are turning in circles on your own. I already stated, that I know, so there is nothing new to see for me in the RPM spec file format specification: I used the words "free text" field from the format specification right from the start in the very first bullet point.
It was you correctly assessing that we will not fix rpmlint and all syntax highlighting editors. Furthermore I always clearly denoted that for a big part of the confusion directly originates from the specification's choice of tags, rpmlint and editors are contributing to and amplifying this.

I conclude that this is also progressing too slowly for you, because you reiterate to points which we already left behind. For example this one:

So, in principle, rpmlint and syntax highlighting have taken either lazy (highlighting, I presume) or overcautious approach (rpmlint?). In our case, the both are doing it wrong and I would even consider it as a bug of the software interpreting %description field in such manner.

"But, it is not up to us to change that." to quote yourself.

If I remember correctly, PackageName was forced by rpmlint as we wanted to have just Name as a tag. Title wasn't proposed, I think. as we used AppData tags as a reference.

Yes, I know. So what?

If we are going to change the tags, we will be still in the mercy of RPM SPEC staying the same. What if they will introduce Title? Or Logo? Chances are low, I admit, but we seem to be going down that rabbit hole.

No, it is just your thoughts now visiting every rat hole in sight, after initially stating:
"Re implementation: I wouldn't mind implementing it - should be simple to do so. So, it wouldn't be hanging too long on that as soon as we agree on what to change."
BTW, I explicitly designed it to be simple to implement.

The statement "we cannot know what the future brings" is a typical killer argument, which from my point of view only discredits the one using it, not the point it is directed at.

More specific terms/discussion:

Logo could be something that is rather fixed and may not have a freedom of drawing something on the background, as some icons may do.

No. A logo is just a logo. Merriam Webster correctly defines it as "an identifying symbol". Nothing more or less.
BTW, companies alter their logos regularly, sometimes even change it radically, hence these arguments do not make any sense to me.

They are not synonyms, but that is probably more important in corporate world. In this respect, icon would be correct to use as a tag in our spec.

I never stated that these are synonyms, rather the opposite. I did state and document (see fourth bullet point) that "icon" is too specific IMO, as this can differ from the program icon used (on the launcher etc.). Thus we shall not use the same word, as this confuses, in addition to the other reasons already provided and documented.

As you requested, I systematically looked for alternatives, but failed to find one: "emblem" is closest, but a bit more specific (in the sense you have been criticising "logo" for), "logotype" just the original, longer version, "insignia" also has a much more specific touch, "impresa" is a very niche word nobody uses, "logogram" just a longer variation, "visual" radically generic ("something to the eye") etc. etc.

If you do not want "logo", please provide an alternative which does not read "icon" (because that is what you continuously are returning to, and maybe that is the whole aim of making me revolving in circles). For me it is absolutely fine, just as all the alternatives I named above, despite being more imperfect.

Edit: It is interesting to read that GitHub prefers the term "logo" over "icon" as a generic term for "an identifying symbol" of either an individual (person), an organisation (group of persons) or a piece of software (e.g., an app), for example(s) read here and there.

Re versioning: we have rather small spec and number of developers using it. In this sense, I would still prefer using new tags as synonyms. In this we disagree.

This is what I call "the sky is blue" killer argument: Name something trivially correct and let it sound as if speaks for or against something else. The size of the spec and the number of its users is completely unrelated to versioning. The last round you stated the opposite "Just looked - we are already at 261 packages!" (so many that nothing can be altered 😉), as if this specification version would enforce any package author to change anything.

To design a specification deliberately without versioning is just an insane concept, because that makes it impossible to address a specific state of the specification in terms of time and content (among humans and technically). Up to now I viewed the lack of versioning as an mishap, which ought to be rectified, but not as a concept (with which goal?).

---

Meta

In the prior rounds of discussion I either agreed to your requests for changes or swallowed them as a compromise until I felt compromised. By your last message, you oppose everything achieved so far, including your own former assessments: You try to fundamentally invalidate the whole action.

I perceive this not only as unfair ("foul play"), but also as breaking the mutual understanding that we try to work together constructively here. I have sensed this pattern in former discussions with you: Suddenly you back out of everything and just fundamentally oppose things without naming reasons (just killer arguments). If I did write something, which triggers this behaviour, please name it.

Working together / collaboration is mutually exclusive to winning on a social level: If the notion of winning socially comes up, implicitly the basis for a collaboration among peers is lost.

Also mind that opposing your own, clear statements undermines trust in all your statements.

---

How to proceed

I update the draft with reasoning for all the arguments brought forth and addressed your wish below:

I would still prefer using new tags as synonyms

O.K., I rephrased the draft to reflect that by detailing the use of the ChumVersion: tag. Can we now proceed with implementing this?

[rinigus]

I would like to ask @piggz or someone else to review your proposal and state whether they like it or not. Right now, it seems that we are the only ones discussing it. I don't want to end up in a situation where we spend our time changing documentation and code and then impose the changes which nobody wants / cares about.

I agree that this discussion is rather tedious and its time to finalize it.

[Olf0]

@nephros, you may have or want to build an opinion on this topic as a very regular contributor of software to the SailfishOS:Chum community repository.

Unfortunately there is no summary of the discussion between @rinigus and me, I also think the the winding course this discussion took with all its turns etc. is hard to summarise. Hence I suggest to either read only the draft proper or the draft and the subsequent discussion in its entirety to gather all aspects.

[nephros]

I must say I'm a bit annoyed by the signal to noise ratio of this. A lot of time spent for little gain.

care less about the thing and more about the people using it

Anyway, I tend so side with most of what @rinigus said in comment 1423068427:

Versioning:

My opinion is, version the specification (and document well the differences), but don't introduce a metadata tag.

It offers no benefit to people writing metadata sections, it's just meta-metadata.
The benefit to parser authors is also questionable , as they will have to deal with legacy and non-conformance anyway. And there is only one parser right now, and it lives in the same git tree as the spec.

IMO, Metadata is implicitly versioned by the "newest" keyword it contains. Yes, it smells of "Early-HTML days" tag soup, but so what. It's a couple of keywords for package display.

Quality will be improved not by defining strict rules, but by making it simple for .spec file authors to say what they want.

If there must be a version tag, I'm also for a single integer. When writing a metadata entry I don't want to look up what X.Y.Z mean, and which Y introduced the keyword I need. It's an API version (like a soname), not a software release version.

rpmlint:

As long as it doesn't actually fail when encountering chum tags, ignore it's obviously wrong output. There are numerous warnings caused by tar_git and the build system in rpmlint, so aiming to shut it up completely is futile.

Although I agree Icon is a bit annoying.

As a nice-to-have, (maybe in the context of #83), document for devs those warnings that are impossible or hard to get rid of, and advise to just ignore them.

[nephros]

(continuing in a new post as sfos browser can't edit posts here).

Url - > Links

Very much for. That's really good.

PackageName -> Title

Okay with that - not convinced it's direly necessary.

Icon

Like others, not sure Logo is a good name and can't think of a better one than Icon,

Maybe keep PackageName and introduce PackageIcon?' One change less, and solves the RPM Icon: confusion issue.

Good point about PackagerName being very similar, but as I'm the originator of that tag and may me the only one using it: I can deal with that. It would also be OK to just make it a Packager, or PackagedBy as there is no (and does not need to be a) PackagerLogin to go with it.

[nephros]

One Issue I have with the current Metadata example/doc is that it is not clear which of the Url: things show up where in the GUI. And that they don't match up with the tag names - e.g. Help vs Discussion Forum.

But that is purely an issue of documenting the relationships of tags with UI handling of them.

[Olf0]

I must say I'm a bit annoyed by the signal to noise ratio of this. A lot of time spent for little gain.

Oh, I think ultimately we (all three) perceive this alike, though when @rinigus and I team up, we excel at this, regularly.

care less about the thing and more about the people using it

Nice statement (never read that so concisely phrased), but I just address what regularly annoys me, as denoted in the second paragraph "Motivation" of the initial posting. This is the classic motivation for Free Software: Try to make your own life easier; which is implicitly something everybody perceives differently due to the "own life" (aka YMMV).

Unfortunately some of your statements WRT the new tags are a bit inconclusive, i.e., they contain pro and contra arguments.

What I gather is:

Versioning

You do not like it, hence this resolves the tie between @rinigus and me. The is no implicit "must", except we define something so.
_{Though it is funny to read, that you explicitly describe my principal consideration in your own, quite different words: "Yes, it smells of 'Early-HTML days' tag soup …". And no, IMO these rules are not "strict", rather loose: Use all the keywords a major version currently allows for, and likely there will be only a single major version ever, "0". When writing a metadata entry one does not have to look up what X.Y.Z means, and which Y introduced a needed keyword: Just read the current Chum spec and inserts its version. The minor and point release numbers are only to indicate to human readers that something changed and how, providing guidance when one overhauls an extant Chum metadata section, which was written according to an older version of the Chum spec.
So what, overboard with the versioning.}

rpmlint

^{Well, some versions of it at the SailfishOS-OBS do indicate a failure due to the Icon: tag in the %description section, but Jolla globally switched on "Treat errors as warnings", hence that never causes a build to fail. Still there are also the syntax highlighting editors and, e.g., sfos-upgrade also contains a real Icon: RPM tag, though commented out (a build script of mine removes the comment mark, putting the Icon: RPM tag into use).
But these points were only the rationale ("motivations") @rinigus demanded to be documented; lastly this is irrelevant, when we aim for implementing something we agree upon.}

Url: → Links:

Hooray, something we all three agree upon. 🎉

PackageName: → Title:

1 + ½ + ½ = 2   A definite majority. 👍

Icon: (→ PackageIcon:)

Because both of you want to stick to the term "Icon", I think your suggestion PackageIcon: is the perfect way to avoid any naming collision, regardless if the behaviour of rpmlint and syntax highlighting editors is deemed erroneous or not! Hence I am all for PackageIcon: to end this enduring discussion, because two of us being for it constitutes a majority. Still I hope @rinigus likes this solution, too.

PackagerName:

^{The similarity is resolved by PackageName→Title and Packager: is a reserved RPM tag name. I do like PackagedBy: better, hence I conclude it is always advisable to have an open discussion with sufficiently allotted time before implementing something to avoid such "quick shots" which turn out to bear drawbacks, later.}

Enhancing the extant documentation

I can take a look at these points in the SailfishOS:Chum GUI app and try to enhance rsp. rectify the documentation when documenting the new tags, as soon they are implemented in a PR, which I can read as reference.

Also mind that there also is the long open issue #43 "Icon file formats and preferred size are not documented" (a year ago I just enhanced the documentation with the little information I know for sure), which IMO just requires someone C++ savvy to read the code. I will gladly document this properly, if someone technically determines …

• if there are other supported formats besides SVG and PNG.
• to what extent bitmap formats are scaled, so there are minimum and maximum advisable resolutions.
• if the graphic has to be in 1:1 aspect ratio and if other aspect ratios are retained or scaled to 1:1.
• etc.

I assume there is / are some Qt call(s) performing some or all of this; if so, it should be sufficient to provide me with a pointer (link) to the documentation of the functions used and where the code is, which uses them; I can still ask, if I do not comprehend how this is implemented and what exactly it does.

How to proceed

When one of you, @nephros or @rinigus, implements a PR for the SailfishOS:Chum GUI app with these three changes (add Links: as a synonym for Url:, Title: as one for PackageName: and PackageIcon: as one for Icon:), I will create a PR with the documentation update: Then both PRs can be reviewed before merging for quality assurance and to check if they are properly aligned. BTW, these must be in two separate PRs, because the new release has to be deployed for a little while, before the documentation update can be merged / released.

Side note: I suggest to perform the mutual reviews among us three, because I do want to avoid starting this discussion again. IMO this should be all about ending this thread in a straightforward and constructive manner.

[Olf0]

@rinigus, is SailfishOS:Chum GUI PR #181 O.K. from your perspective?

I will try to overhaul the current spec with the knowledge I gained in the year since I last overhauled the SailfishOS:Chum metadata specification (also addressing issue #43) this weekend, but leave the tag information as it is. When you provided some feedback ("O.K." is fully sufficient 😉), I will create a PR for the Chum metadata specification reflecting the changes in Chum GUI PR #181.

[rinigus]

Missed that OR, sorry. LGTM

[Olf0]

If someone wants to take a look at the adaption of the SailfishOS:Chum metadata definition (PR #109) to Metadata: parse new names (SFOS:Chum GUI app PR #181). Because I updated some descriptions before documenting the four revised tags, the changes are so trivial, that IMO they do not need to be formally reviewed; but if someone has the time for QA, this is always welcome. As the SailfishOS:Chum GUI application 0.6.0 has already been published, which supports version 1 of the SailfishOS:Chum metadata definition (by aforementioned PR #181), I plan to merge PR #109 the upcoming weekend.

[Olf0]

Done.