OpenAjax Hub 1.0 Specification Issues

From MemberWiki

Jump to: navigation, search
<--previous       contents--^      next-->


Contents

Appendix C: ISSUES

This appendix lists various closed issues relevant to this specification.

The write-ups on this wiki page for individual issues should not go beyond executive summaries. Detailed write-ups should be posted elsewhere and referenced from this page.

OPEN ISSUES (most recent issues listed at top)

None.

MOST RECENTLY CLOSED ISSUES (most recent issues listed at top)

Hub 1.0 Issue 17: Allow arbitrary text at end of OpenAjax.hub.registerLibrary() version strings?

Original write-up

This is not an earth-shattering issue.

Right now the Hub specification says that version strings must be of the form #[.#]* (i.e., "1", "1.0", "1.1", "1.0.1.3"). Would it be better to allow arbitrary characters after the #[.#]* so that version strings could say things like "1.1beta2" or "2.1 build 9504"?

The idea is that version number comparisons in JavaScript would still be possible, with the only extra requirement being that developers probably need to include some simple regex logic to extract the numeric part of the version string before invoking major/minor version number comparison logic (that they also have to write).

If we allow extra characters after the #[.#]*, then we would have to make a small change to the wiki pages that hold the specification but no changes are required to the open source implementation.

Note that we have an optional extraData parameter to OpenAjax.hub.registerLibrary(). The Hub specification right now says that "This field might be used to hold build or release numbers or indicate alpha/beta status."

Jon's proposed resolution #1

At the next Interoperability phone call, let's discuss the issue for a few minutes so everyone understands, then the people on the phone call can express their preferences. If there is a majority in favor of allowing alpha data at the end of the version string, let's go with that, otherwise leave things alone. Whatever, it's not very important and we shouldn't spend much time on it.

Jon's proposed resolution #2 (2007-10-11)

Jon sent email to the group with the following proposal.

Instead, my proposal is that we tweak the current language within our specification to allow arbitrary text after leading numeric part of the version string. If software needs to do version comparisons, then they will have to use a regexp to first extract leading numeric and decimal point characters.This isn't much extra burden because version comparisons will need to a bit of logic to split the numeric tokens and then compare each of the tokens in turn. Below is my proposed revised text to replace the current text found at (http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_Libraries#OpenAjax.hub.registerLibrary.28prefix.2C_namespaceURI.2C_version.5B.2C_extraData.5D.29). Besides adding text to allow extra text after the version string, I added extra text to make sure developers understand how version comparisons are supposed to work.
version
(Required) Version number in the form of #[.#]*, such as "1", "1.1" or "1.20.2", followed by an optional arbitrary string (e.g., "1.20.2Beta" or "1.1 Build 543"). The leading numeric part of the version string allows script to determine which version of a particular Ajax library has been loaded, using equal/greater-than/less-than comparisons. The first (non-negative) integer token of the leading numeric part SHOULD reflect the library's major release number. The second (non-negative) integer token of the leading numeric part SHOULD reflect the minor release number. The third (non-negative) integer token of the leading numeric part SHOULD reflect the (next level down) minor release ("minor-minor" release number). It is acceptable to include other numeric values (4th, 5th, etc.) although probably not useful. To illustrate, with the value "1.20.3 beta 7", the major release is "1", the minor release is "20", and the minor-minor release is"3". The optional trailing arbitrary string must begin with a character other than a numeric character (i.e., 0-9) or period character. In version comparison logic, first extract out the leading numeric part of the version string; then tokenize the numeric part. First do a numeric comparison of major version tokens. If equal, then compare minor versions. If equal, then compare minor-minor versions. Etc. Missing tokens are equivalent to zero.

Adam Peller (with Matthias' agreement) suggested that we do a minor bit of rewording for the 2nd, 3rd, etc. parts of the numeric part of the version string so that it says "SHOULD (if present) reflect" instead of just "SHOULD reflect".

Matthias suggested that different releases have different numeric version numbers, such as "2.1.1009 alpha" and "2.1.1053 beta", and not just "2.1 alpha" and "2.1 beta" (which compare the same), arguing that most systems have distinct build numbers for each release. He proposes the following text: "Trailing text is not part of the version. Submitting a new version to the public the version has to be incremented.". Jon responded saying that this sounds like a good recommendation to toolkit developers on a SHOULD basis, but we can't tell them how to do their versioning, so we can't say that toolkits MUST have higher version numbers for each minor release.

Jon's proposed resolution #3 (2007-10-16)

Jon sent email to the group with the following proposal.

Instead, my proposal is that we tweak the current language within our specification to allow arbitrary text after leading numeric part of the version string. If software needs to do version comparisons, then they will have to use a regexp to first extract leading numeric and decimal point characters.This isn't much extra burden because version comparisons will need to a bit of logic to split the numeric tokens and then compare each of the tokens in turn. Below is my proposed revised text to replace the current text found at (http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_Libraries#OpenAjax.hub.registerLibrary.28prefix.2C_namespaceURI.2C_version.5B.2C_extraData.5D.29). Besides adding text to allow extra text after the version string, I added extra text to make sure developers understand how version comparisons are supposed to work.
version
(Required) Version number in the form of #[.#]*, such as "1", "1.1" or "1.20.2", followed by an optional arbitrary string (e.g., "1.20.2Beta" or "1.1 Build 543"). The leading numeric part of the version string allows script to determine which version of a particular Ajax library has been loaded, using equal/greater-than/less-than comparisons. The optional trailing arbitrary string must begin with a character other than a numeric character (i.e., 0-9) or period character. The optional trailing string must be stripped before invoking version comparison logic.
The first (non-negative) integer token of the leading numeric part SHOULD reflect the library's major release number. If present, the second (non-negative) integer token of the leading numeric part SHOULD reflect the minor release number. If present, the third (non-negative) integer token of the leading numeric part SHOULD reflect the (next level down) minor release ("minor-minor" release number). It is acceptable to include other numeric values (4th, 5th, etc.) although probably not useful. To illustrate, with the value "1.20.3 beta 7", the major release is "1", the minor release is "20", and the minor-minor release is "3".
In version comparison logic, first extract out the leading numeric part of the version string; then tokenize the numeric part. First do a numeric comparison of major version tokens. If equal, then compare minor versions. If equal, then compare minor-minor versions. Etc. Missing tokens are equivalent to zero.
Subsequent releases of a given toolkit MUST have version numbers that are greater than or equal to previous releases. Although not required, it is recommended that each release have a higher version number than previous releases. One technique to accomplish this is use the build number for the 3rd token (the "minor-minor" release number), such as "1.3.2065", where the major version is "1", the minor version is "3", and the build number is "2065".

Resolution and rationale

After iteration over details, Jon's final proposal was submitted via email and was acceptable to the committee. The rationale for allowing arbitrary text at the end was mainly that it had some descriptive value and did not materially harm numeric-based version comparisons so long as the specification was clear enough about the processing model for version comparisons. Along the way, we added various clarifications to make sure toolkit developers and application developers all do things under the same set of assumptions.

OTHER CLOSED ISSUES

For issues closed previously, see


<--previous       contents--^      next-->
Retrieved from "http://www.openajaxalliance.org/member/wiki/OpenAjax_Hub_1.0_Specification_Issues"
Personal tools