Application ID casing documentation is kind of inconsistent

[strugee]

https://docs.flatpak.org/en/latest/conventions.html#application-ids states:

Org.Example.App
The domain portion of the ID must be in lowercase, and while not required, the application portion is recommended to be in lowercase as well. Therefore, you should use org.example.app.

But there are loads of examples, in particular from GNOME, of the application portion being uppercased. Flathub is littered with them and even that very same docs page uses an uppercased application component in an example.

Some clarity on this discrepancy would be nice. Or, perhaps this recommendation should just be dropped, especially if there is no compelling technical reason for it.

[TingPing]

There is no technical difference. I feel like the current wording is pretty clear, its not required, its a recommendation.

Most of the decision comes down to pre-existing names (like dbus services).

[strugee]

The current wording is clear, but what's less clear is why it is a recommendation, but not required.

Most of the decision comes down to pre-existing names (like dbus services).

The docs need to serve greenfield development projects too. For brand-new projects without any D-Bus consumers, etc. this is an important choice, and if you aren't deep into Linux app development already, a pretty confusing one - specifically because the docs say it is not actually required. The natural next question becomes, under what circumstances would I ignore this recommendation?

I personally find this especially confusing because the same section links to the D-Bus spec and the Desktop Entry spec, both of which make conflicting recommendations... except it also links to the AppStream spec, which agrees with the Flatpak recommendation.

I understand that I'm complaining about specs that Flatpak is not directly responsible for, but the end result is the same: Flatpak has linked to these specs, and as a new developer, that is very confusing.

If lowercase really is preferred now, a short note about "you might see older applications and specs referencing/using a capitalized camel-case final component, but this is a legacy convention and the modern preference is for lowercase" would help a lot. It doesn't have to be long.

[bbhtt]

The docs are fine. "Flathub is littered with them" is no metric at all.