Document style of "support" comments

[markelog]

Every time we have a rewrite or drop support for some browser we engage (at least in Core) in discussion of how to properly write those support comments:

Support: IE8<9
IE8+
IE11<
...

We need clear understanding of how to write those comments, so we can leave those discussion behind and focus on code instead of flaming the pull/issue thread with pointless posts.

[mgol]

👍 to documenting that. This is my understanding of current de-facto rules (a little extended) that we could codify on a case by case basis (I'm omitting the // Support: prefix and assume that data for specific browsers is separated using ,):

1. Browser has a bug in versions k-n, we don't know if it was fixed in n+1:

Browser k-n+

1. Browser has a bug in versions k-n, it's fixed in n+1:

Browser k-n

1. Browser has a bug in version n, we don't know if it was fixed in n+1:

Browser n+

1. Browser has a bug in version n, it's fixed in n+1:

Browser<n+1

1. Browser has a bug in version k, n (k < n but maybe also k < n-1), we don't know if it was fixed in n+1:

Browser k, n+

1. Browser has a bug in version k, n (k < n but maybe also k < n-1), it was fixed in n+1:

Browser k, n

or

Browser<n+1

(the latter ignores information about version k)

This convention would mean that unless the last version mention is followed by +, we assume it was fixed in the next version.

The main drawback of this convention is IMO that Browser n and Browser<n+1 seems interchangeable and we should have a concrete convention everywhere.

This is important for every project so cc @jquery/core @scottgonzalez @arschmitz @jzaefferer.

[mgol]

BTW, if we don't come up to a concrete conclusion quickly I'd like to merge jquery/jquery#1837 in its current form; it's quite large and I don't want to have to continue to rebase it and solve conflicts with other PRs; it takes time for no reason.

[markelog]

This shouldn't be a blocker for jquery/jquery#1837

[mgol]

@gibson042 comment from jquery/jquery#1837 (comment):

I don't know that we've ever established a consensus on this, but I personally see more value in IE<9 (i.e., preserving fix information even for browsers that have rotated out of our support window).

[jzaefferer]

Browser has a bug in version n, it's fixed in n+1:
Browser<n+1

Shouldn't this say "up to version n"? Then Browser n would mean "bug in (only) version n".

I'd also always put a space after "Browser', so Browser <n

Browser isn't a great keyword, in jQuery UI we have plenty support comments referring to jQuery versions, like this:

// Support: IE and jQuery <1.9

I'm fine with replacing " and " with ", ".

[gnarf]

So hold on. Is that last example to support IE with jQuery 1.9? Or IE and
any other browser in jQuery <1.9?
On Dec 8, 2014 8:38 AM, "Jörn Zaefferer" notifications@github.com wrote:

Browser has a bug in version n, it's fixed in n+1:
Browser<n+1

Shouldn't this say "up to version n"? Then Browser n would mean "bug in
(only) version n".

I'd also always put a space after "Browser', so Browser <n

Browser isn't a great keyword, in jQuery UI we have plenty support
comments referring to jQuery versions, like this:

// Support: IE and jQuery <1.9

I'm fine with replacing " and " with ", ".

—
Reply to this email directly or view it on GitHub
#95 (comment)
.

[scottgonzalez]

In that specific case, I'm not sure. @mikesherov wrote it, so hopefully he knows. It's related to focus and the behavior of .focus() changed in 1.9, so it could go either way.

We do have other examples of support comments that are more complex than just a browser:

// Support: IE<9, Opera in jQuery <1.7
// Support: Voiceover on OS X, JAWS on IE <= 9

[gnarf]

It might be better to never allow two "setups" on the same // Support: line. In that last example of scott's I think it's better to look like:

// Support: IE<9
// Support: Opera in jQuery<1.7
// Support: Voiceover on OS X
// Support: JAWS on IE<=9

This would remove any ambiguity in the last example, and we'd know its only support for IE in jQuery <1.9

[scottgonzalez]

+1 for splitting across multiple support lines.

[mgol]

@jzaefferer

Browser has a bug in version n, it's fixed in n+1:
Browser<n+1

Shouldn't this say "up to version n"? Then Browser n would mean "bug in (only) version n".

I assumed only the information I wrote, i.e. we know the bug is in version n and doesn't appear in n+1.

There are interesting cases, though, where a bug doesn't exist in Android 2.3 and >=4.4 but exists in 4.0-4.3. Most of the time we don't check every older one when we already know the workaround will be needed because of a newer browser.

I'd also always put a space after "Browser', so Browser <n

This seems weird to me. I treat both parts as arguments to the < relation so we either should have spaces on both sides or on none. In Core we use both style forms but we've recently started changing to the spaceless one; most of our support comments adhere to that formatting currently. I don't have strict preference here (although maybe the spacey one seems more in line with the general jQuery spacey code style).

[mgol]

@gnarf

It might be better to never allow two "setups" on the same // Support: line.

Good idea.

[dmethvin]

Yeah, 👍 on having only one setup per line. If there is a further explanatory comment for a specific setup, should each follow in a comment line below? e.g.: (totally made up comments)

// Support: IE<9
// Event doesn't bubble properly
// Support: Opera in jQuery<1.7
// Core patch #2421 made this work properly in 1.7

[mgol]

@dmethvin: Yeah, definitely above the comment (that would match current
Core comments).