Extension compatibility versioning guideline

Add-ons for Pale Moon and other applications
General discussion, compatibility, contributed extensions, themes, plugins, and more.

Moderators: FranklinDM, Lootyhoof

User avatar
Moonchild
Pale Moon guru
Pale Moon guru
Posts: 35402
Joined: 2011-08-28, 17:27
Location: Motala, SE
Contact:

Extension compatibility versioning guideline

Unread post by Moonchild » 2017-03-22, 21:22

This is a guideline for everyone creating extensions for Pale Moon, specific to creating your install.rdf and indicating version compatibility with Pale Moon, and to clarify what to use and what to avoid (and why). Because of the slightly strange way the VersionComparator function works inside the browser, there are a few things that may seem counter-intuitive at first.

As a general guideline, you should stick to the following rules:
  • Set your minVersion in your targetApplication block to the lowest version of Pale Moon that your extension fully supports:
    • Use a full, 3-part version number, e.g. 27.0.0, not "27" or "27.0".
    • If you want to indicate minimum compatibility with all versions in a specific milestone, use .0.0a1 (e.g. 27.0.0a1). This is needed because otherwise any pre-releases (alpha/unstable, beta, etc.) will not be considered compatible. The VersionComparator considers 27.0.0a1 to be less than 27.0.0; if you're used to direct string comparisons, this may seem incorrect, but that's how this thing works ;)
  • Set your maxVersion in your targetApplication block to the highest known and existing milestone version of Pale Moon that you can reasonably expect the extension to support.
    • When indicating guaranteed compatibility with everything in a certain milestone (common), use a single asterisk after the milestone, e.g. 27.*
    • You should only use a higher milestone version if there is a reasonable assumption based on published/discussed information that the higher milestone will, in fact, support your extension.
    • You should never use * to indicate maximum compatibility ("all versions in the future, forever"). Although it's a quick way of saying "I never expect this to stop working", it is problematic from a technical point of view (see below) since you cannot guarantee that the extension will be compatible with what might be a completely different platform of a new milestone, and your extension can in that case break the browser. Using an existing version with an asterisk is not necessarily a problem because extensions are assumed to be forward compatible unless specified otherwise. This has been the case sine v11 or so.
  • If your extension relies very heavily on specifics of the user interface (e.g. complete themes), you may want to use small version ranges corresponding specifically to major updates, and enable "strictCompatibility" in install.rdf:

    Code: Select all

    <em:strictCompatibility>true</em:strictCompatibility>
  • To allow point releases and security updates, you should at most indicate 2 version parts for your maxVersion, e.g. 27.2.*, so these updates can always be installed without making your extension incompatible.
Why not maxVersion=* ?
The way the extension installer handles extension versions, it will accept extensions that have a lower maxVersion than the current application version unless "strictCompatibility" is set. This means that even if your maxVersion is 27.*, people can still install it on 28.0 or 29.0, for example. At the same time, it allows for control mechanisms to be used to stop incompatible versions from being installed or enabled if they are really not compatible (e.g. if the browser core has significantly changed that makes certain versions have a hard incompatibility). If you would use * instead, there is no way for the extension installer to know, and it will happily install completely incompatible extensions as a result, assuming full compatibility with whatever version of the browser is being used.
Last edited by Moonchild on 2017-03-22, 21:26, edited 2 times in total.
"Sometimes, the best way to get what you want is to be a good person." -- Louis Rossmann
"Seek wisdom, not knowledge. Knowledge is of the past; wisdom is of the future." -- Native American proverb
"Linux makes everything difficult." -- Lyceus Anubite

User avatar
JustOff
Banned user
Banned user
Posts: 2083
Joined: 2015-09-03, 19:47
Location: UA

Re: Extension compatibility versioning guideline

Unread post by JustOff » 2017-03-23, 12:37

I understand the reasons and respect this rules, but even so I have to say that the ban of 'maxVersion = *' is too strict.

I think it's important because a lot of extensions already uses 'maxVersion = *', including almost all add-ons that made using SDK/PMkit. And at the time when Mozilla finishes destroying the ecosystem of classic add-ons, I believe that Pale Moon should show an opposite example of sensitive attitude towards developers, even if we know they are far from perfect (but all of us are not perfect too).

So my message is simple: please, do not enforce the prohibition of 'maxVersion = *' until 2018, at least do not apply this restriction automatically at the program level in the APMO or browser core.

PS: I'll update maxVersion of all extensions that I support in a few days, so this request has nothing to do with my personal convenience.

User avatar
Moonchild
Pale Moon guru
Pale Moon guru
Posts: 35402
Joined: 2011-08-28, 17:27
Location: Motala, SE
Contact:

Re: Extension compatibility versioning guideline

Unread post by Moonchild » 2017-03-23, 12:53

It's not a ban, it's a guideline/directive. It's also rooted in technical procedure and implementation, and has nothing to do with opinion.

If you understand what I wrote above, then you understand that 27.* and * will effectively be the same if you don't enforce strict compatibility, from the extension being able to be installed point of view.[1]
But where it differs essentially is that using * will prevent restriction of installation of extensions when it is required, e.g. when the core of the browser changes so significantly that extensions must be updated to work or not break the browser.

While it is possible to use *, you shouldn't. It doesn't matter how many extensions do this (mostly out of historical reasons[2]). if you go in and make an extension for Pale Moon, you should keep to this guideline and never use *.

[1] Pale Moon will not enforce maxversion unless you indicate it should be strict. So all you do with * is making it completely ambiguous for the browser and unable for us as core devs to respond to known incompatibilities except through a blocklist, which is unnecessary work if extension devs simply stick to indicating proper full-compat ranges.
[2] Initially, extension compatibility was enforced because 2.0, 3.5 and 3.6 needed extensions to be changed to be compatible. When Firefox went rapid-release, extension developers got tired of having to update their extension every cycle to make it install (and often nothing else) so they started using * even if it was not recommended, ever, to do so. Eventually, this strict check was lifted by Mozilla, resulting in [1], but that didn't stop extension devs from using * because they clearly didn't inform themselves or couldn't be bothered to test things and keep a record of the range they knew had full compatibility.
"Sometimes, the best way to get what you want is to be a good person." -- Louis Rossmann
"Seek wisdom, not knowledge. Knowledge is of the past; wisdom is of the future." -- Native American proverb
"Linux makes everything difficult." -- Lyceus Anubite

User avatar
JustOff
Banned user
Banned user
Posts: 2083
Joined: 2015-09-03, 19:47
Location: UA

Re: Extension compatibility versioning guideline

Unread post by JustOff » 2017-03-23, 14:36

Moonchild wrote:While it is possible to use *
I received a notice from Add-ons Team that "In the future maxAppVersions of * will be rejected by the Add-ons Site Software" and was worried about possible negative impact if this rejection will be enforced too soon. Now I got the answer and hope I understand it right.
Moonchild wrote:you shouldn't.
I definitely will not! I also updated the PMkit documentation draft.

New Tobin Paradigm

Re: Extension compatibility versioning guideline

Unread post by New Tobin Paradigm » 2017-03-23, 18:01

Right.. So.. Let me state once again I am not a member of the Add-ons Team anymore. I am, however, a free agent.. That means I can work on things where needed without being apart of an organization. Also, as has been stated previously I have a commitment to fulfill with the Phoebus software which I intend on doing.

That being said, the Add-ons Site is a Pale Moon service and isn't a free for all.. It does have its own standards and is administrated over by the Add-ons Team of which I am not apart of anymore. The software is created in kind with the policies of which I may have originated but am not in charge of enforcing. At this time and with Phoebus 1.5 this won't be enforced by the software because it still uses the manifest files which are fairly freeform.

However, to best serve users of the service the software continues to evolve and will get to a state slated for Phoebus 2.0 to be SQL driven rather than manifest driven. One feature that will help make things easier will be that much of the required metadata can be directly extracted from install.rdf rather than manually inputted by add-on developers on the Add-ons Site. This will be less error prone in some cases and reduce the work required for updates.

As the software evolves and becomes more cohesive and consistent and friendly to add-on developers some items should be made firm or hard requirements. One of these is sane version numbers in target applications. While some may find it arbitrary or restrictive, which it isn't and is now documented above, it will be a requirement to use the service. Now, while the software I wrote will enforce good practices by training those to do things properly.. AMO, in contrast, simply modifies, mutates, and repackages your choices to match their own without even telling you because it is hidden somewhere in the Terms of Use that they can do this.

Of course, one may not agree with either policy or that you are required in the rare cases of where it actually matters to do things properly. Well, that is why there is even more choice. You can always just host your extension your self, providing your own webspace and updateURL and set whatever insane value for maxAppVersion you want and the Add-ons Team, which again I am not apart of, will still list it as an indexed (external) add-on if you ask them to.

I hope this clears up any remaining confusion.

I am the New Tobin Paradigm reminding you all.. I don't have to do anything.. but I do anyway!

Peace!

Locked