There is a need to decide when to remove the version macro badges from contrib extension documentation.
Context: For documenting XS extensions (bundled) we apply this guideline, when removing version macro badges, but we don’t have guidelines for contrib extensions, which don’t have the notion of LTS.
Option 1: Remove version badges older than 1 year, to stay aligned with XS extensions.
Pros:
consistency with the existing XS rule
keeps the badge visible during the period when users are most likely still on the previous version
Cons:
the info isn’t at hand, you need to check git/Nexus to find out whether a version was released more than 1y ago
easy to miss / forget to remove
needs periodic/centralized checking system
Option 2: Remove after N releases. My preference is N=1, (i.e. remove after each release).
Pros:
aligns with the stated principle in the Doc Guide that “Documentation must be written from the perspective of the latest version.”
avoids cluttering the page: the contributor adds documentation after a release using the version macro to note when a feature became available, and removes the previous version badge at the same time
the information is somehow still available on the extension’s versions page, (e.g. JIRA extension versions)
Cons:
risks removing the badge right when it’s most useful
Note: We could also pick a different value for N, for example N=12, which would approximate the 1-year from Option 1, considering that several contrib extension might have in 1y a very different number of releases.
My preference leans towards option 2 with N=1, but there might be cons I haven’t noticed, or bigger pros for option 1.
-1 on how it’s stated since that’s almost the same as saying that using the version macro is useless.
The important part is that we need to NOT count bug fix releases (i.e. X.Y.Z where Z > 0) since there can be a lot quickly and they shouldn’t count.
The N approach is interesting. Since releases of extensions vary a lot depending on the extension, I think it makes more sense than option 1.
I think N=1 might be acceptable. The problem is that if users don’t upgrade their extensions often, they’ll read doc thinking that some documented feature don’t work since it doesn’t work on their instance.
N=6 would be better in this regards. Since extensions are smaller than XS, we should expect lower LTS timeframes (takes less time to stabilize in theory). It would mean that when Extension XYZ releases, say, version 1.10(.0) then all version macro with values <= 1.4 should be removed. The harder part is when the major increases. For example, say version 2.0(.0) is released. We now need to find what -6 versions mean, so we need to check the history of the releases; But I still think that’s ok. It’s ofc still a lot more complex than N=1.
Honestly, I don’t think it’s really possible to find a common rule that works for all extensions. There are simply way too many differences in their lifecycles.
That’s not an answer What are you going to do when editing a page with version macros? Are you proposing to never remove them? If you propose to still remove them depending on the extension, what are the rules you’ll apply?
I agree with Thomas there is no defined rules for contrib extensions. We also don’t have a clear rule for the use of the @Depratecated annotation for contrib extensions.
An option could be to have a default rule (e.g., anything from a version older than 2 years don’t need to be wrapped in a version macro), and to allow project leaders to override the rule if they want to.
Though, if we agree on the idea, we need to find a place to document the project specific rule (e.g., the readme.md).
My point is that it does not make any sense to try to find a rule that work for all extensions. At best, we can document various possible rules and decide in a case by case basis which one to apply (the default, or if you don’t know the rule, being to not remove version macros, yes).
What are you going to do when editing a page with version macros? Are you proposing to never remove them? If you propose to still remove them depending on the extension, what are the rules you’ll apply?