696273 - Remove explicit references to version numbers in the documentation contents

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P2)

Description

[Will Bamberg [:wbamberg]]

Currently when we release a new version of the SDK, we have to update a number of files which embed the version number. We'd like to get away from that, enable the SDK to work out its version either from an explicit .version file or from a Git tag, and interpolate that into the relevant places.

Currently the SDK docs embed the version in "installation.md":

"At the moment, the latest stable version of the Add-on SDK is HARDCODED_VERSION"

It would be possible to enable the documentation generator to use some kind of template system keep the embedded version up to date. However, we don't think those references to the version justify the extra complexity and processing involved in integrating such a system.

Instead, we should simply remove those references, and in place of that interpolate the version into the documentation header, for example underneath the "ADD-ON SDK" site title. This would be much simpler to do, and would arguably be more useful.

Comment 1

[Brian Warner [:warner :bwarner]]

In bug 704519 I'm working on adding code to automatically derive a version number from git metadata. Part of that branch adds a quick hack to replace any instances of $SDKVERSION in the .md files with the current version string, during 'cfx docs' or 'cfx sdocs'. I'm not sure which way you want to go, but once that patch lands, you'll have the tools to do the embedded-version scheme if you want.

(It might also be nice to have at least one copy of the sdkVersion in the docs, maybe in a footer or on the front page somewhere, to reassume folks that they're looking at docs which correspond to the code they're really using. My patch has a strawman addition of $SDKVERSION in welcome.md, but I'd like to find a better / more-appropriate place for it).

Comment 2

[Will Bamberg [:wbamberg]]

Attachment: Patch to insert version into docs header

It seems that we crossed over on this :-).

Here's a patch that reads the .version file and writes it into the docs header. I also removed all the current references to the version from installation.md (I think this is the only spot where version is manually edited in the docs). 

> (It might also be nice to have at least one copy of the sdkVersion in the
> docs, maybe in a footer or on the front page somewhere, to reassume folks
> that they're looking at docs which correspond to the code they're really
> using. My patch has a strawman addition of $SDKVERSION in welcome.md, but
> I'd like to find a better / more-appropriate place for it).

Agreed, and I think header/footer is better, so people don't have to navigate to some arbitrary place to find it. Footer is less obtrusive than header, but I think this patch looks all right.

So given that we have $SDKVERSION, we can either:

- just take this patch, or some variant on it, or:
- we can take this patch or some variant _and_ use $SDKVERSION to keep the version stuff in installation.md

At this stage I'd probably vote for removing the version stuff from installation.md, but I'm happy to go with either.

One thing, though, is that the current installation.md is misleading where it says: "the most recent stable version is $SDKVERSION". That's not the most recent version, that's just the version whose docs you are looking at. If I download v1.2, then 1.3 ships, then my downloaded SDK will still tell me that the most recent version is 1.2. So if we do keep stuff about versions in installation.md, that ought to be fixed.

Finally, I just noticed that installation.md also says that the SDK requires "Firefox version 4.0 or later", which is a much worse problem. Do we also need $FIREFOX_MIN_VERSION?

Comment 3

[Brian Warner [:warner :bwarner]]

Your patch looks good.. if it lands before mine, then I'll amend mine to change your open(os.path.join(root, VERSION_FILE), "r").read() to a '_version.get_versions()["version"]', and leave out my $SDKVERSION changes. That should work properly, I think.

As for $FIREFOX_MIN_VERSION, that's a whole 'nother can of worms. I posted an idea to the mailing list, to have a table in the code that maps ranges of SDK versiond to FF min/max versions (and min/max for other applications too, I suppose). If we did something like that, then $FIREFOX_MIN_VERSION would be feasible. Not sure if it's a good idea or not, but at least it'd be feasible.

Comment 4

[Myk Melez [:myk] [@mykmelez]]

Comment on attachment 576321 [details] [diff] [review]
Patch to insert version into docs header

Review of attachment 576321 [details] [diff] [review]:
-----------------------------------------------------------------

Woot!

Comment 5

[[github robot]]

Commit pushed to https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/1ae8780c3f2e9c19bceafe9bb0d7bbe9feeb9265
Bug 696273 - Remove explicit references to version numbers in the documentation contents; r=@mykmelez

Comment 6

[[github robot]]

Commit pushed to https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/1ae8780c3f2e9c19bceafe9bb0d7bbe9feeb9265
Bug 696273 - Remove explicit references to version numbers in the documentation contents; r=@mykmelez