Hi,
The issue of how to use @since annotations recently came up in the code review. Those are essential for extension developers who want to target multiple MediaWiki versions with one codebase. I think we should come up a standard way to use those.
Without further talk, here are some issues we need to agree upon: 1. Should every new class have a @since annotation 2. Should every new function have a @since annotation 3. Should every new method have a @since annotation 4. Should other things have a @since annotation 5. Should we remove @since annotations of methods at some point
I think 1) and 2) are uncontroversial. I think that in 3) having @since is redundant if the version is the same as in the @since for the class. For 4) I think the answer should be yes, if it can be used/accessed by other code. I also think that @since annotations for versions that are unsupported *can* be removed, but there is no harm to keep them around.
What are your opinions on these issues, or can you can come up with other issues related to @since that should be discussed? In short: we need to agree on a style, document it, stick to it and enforce it on the code review.
I hope to get a little more comments than my recent request for comments regarding the Message class naming issues :) There are more issues besides this one, for example Jeroen has a wishlist [1] of additions to coding conventions, but let's concentrate on just @since annotations in this thread.
[1] https://secure.wikimedia.org/wikipedia/mediawiki/wiki/User:Jeroen_De_Dauw/Co...
Thanks,
-Niklas
Hey,
I think methods should have the @since annotation, as they can be added in a later version then the one the class was added in. This makes them non-redundant, so in no case should they be removed.
Cheers
-- Jeroen De Dauw * http://blog.bn2vs.com * http://wiki.bn2vs.com Don't panic. Don't be evil. 50 72 6F 67 72 61 6D 6D 69 6E 67 20 34 20 6C 69 66 65! --
On 15 August 2010 13:27, Niklas Laxström niklas.laxstrom@gmail.com wrote:
Hi,
The issue of how to use @since annotations recently came up in the code review. Those are essential for extension developers who want to target multiple MediaWiki versions with one codebase. I think we should come up a standard way to use those.
Without further talk, here are some issues we need to agree upon:
- Should every new class have a @since annotation
- Should every new function have a @since annotation
- Should every new method have a @since annotation
- Should other things have a @since annotation
- Should we remove @since annotations of methods at some point
I think 1) and 2) are uncontroversial. I think that in 3) having @since is redundant if the version is the same as in the @since for the class. For 4) I think the answer should be yes, if it can be used/accessed by other code. I also think that @since annotations for versions that are unsupported *can* be removed, but there is no harm to keep them around.
What are your opinions on these issues, or can you can come up with other issues related to @since that should be discussed? In short: we need to agree on a style, document it, stick to it and enforce it on the code review.
I hope to get a little more comments than my recent request for comments regarding the Message class naming issues :) There are more issues besides this one, for example Jeroen has a wishlist [1] of additions to coding conventions, but let's concentrate on just @since annotations in this thread.
[1] https://secure.wikimedia.org/wikipedia/mediawiki/wiki/User:Jeroen_De_Dauw/Co...
Thanks,
-Niklas
-- Niklas Laxström
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
"Jeroen De Dauw" jeroendedauw@gmail.com wrote in message news:AANLkTin9BKBSq2VKjDosbgs1e9CmF9yz1w8JniYSoOHW@mail.gmail.com...
Hey,
I think methods should have the @since annotation, as they can be added in a later version then the one the class was added in. This makes them non-redundant, so in no case should they be removed.
Cheers
-- Jeroen De Dauw
Don't panic. Don't be evil. 50 72 6F 67 72 61 6D 6D 69 6E 67 20 34 20 6C 69 66 65! --
On 15 August 2010 13:27, Niklas Laxström niklas.laxstrom@gmail.com wrote:
Hi,
The issue of how to use @since annotations recently came up in the code review. Those are essential for extension developers who want to target multiple MediaWiki versions with one codebase. I think we should come up a standard way to use those.
Without further talk, here are some issues we need to agree upon:
- Should every new class have a @since annotation
- Should every new function have a @since annotation
- Should every new method have a @since annotation
- Should other things have a @since annotation
- Should we remove @since annotations of methods at some point
I think 1) and 2) are uncontroversial. I think that in 3) having @since is redundant if the version is the same as in the @since for the class. For 4) I think the answer should be yes, if it can be used/accessed by other code. I also think that @since annotations for versions that are unsupported *can* be removed, but there is no harm to keep them around.
What are your opinions on these issues, or can you can come up with other issues related to @since that should be discussed? In short: we need to agree on a style, document it, stick to it and enforce it on the code review.
I hope to get a little more comments than my recent request for comments regarding the Message class naming issues :) There are more issues besides this one, for example Jeroen has a wishlist [1] of additions to coding conventions, but let's concentrate on just @since annotations in this thread.
[1] https://secure.wikimedia.org/wikipedia/mediawiki/wiki/User:Jeroen_De_Dauw/Co...
Since it won't be possible to tell the difference between "this block had a @since once but it has now been removed" and "no one's got around to putting a @since on this block yet", we should not create instances of the former case until we have eliminated the latter.
--HM
On Sun, Aug 15, 2010 at 7:27 AM, Niklas Laxström niklas.laxstrom@gmail.com wrote:
The issue of how to use @since annotations recently came up in the code review. Those are essential for extension developers who want to target multiple MediaWiki versions with one codebase. I think we should come up a standard way to use those.
I think @since annotations are probably useless. You can't reliably tell if an extension will work on an old version without actually testing it on the old version, and if you do that, you can figure out what works by the error messages. Just because a method or class was present doesn't mean it worked the same way, so @since is not enough. It's got to be less work to just try it than to check every single one of the dozens or hundreds of methods you use for compatibility, too (which no one is going to do).
If you do want to find out if a method is in the version you're targeting, there's a very easy way: check out the branch in SVN and look in the file. Or use ViewVC. It's not really harder than looking in the source code. On the other hand, manually adding @since clutters the comments, makes that much less code fit on one screen, and will create zillions of cleanup commits (which we already have too many of).
So I think we shouldn't use @since at all, personally.
I think @since annotations are probably useless.
I disagree, and know that quite some other extension developers do to. Have you actually been in the situation where you are writing an extension that needs to be compatible up to a certain previous MediaWiki release, and where forced to go look where every method, class and hook was added on ViewVC? I have, and can tell you it's not fun or productive. Of course, if you do only core developement and are familiar with most of the code and it's history, then yes, it's not terribly useful for you personally.
-- Jeroen De Dauw * http://blog.bn2vs.com * http://wiki.bn2vs.com Don't panic. Don't be evil. 50 72 6F 67 72 61 6D 6D 69 6E 67 20 34 20 6C 69 66 65! --
On 15 August 2010 19:36, Aryeh Gregor <Simetrical+wikilist@gmail.comSimetrical%2Bwikilist@gmail.com
wrote:
On Sun, Aug 15, 2010 at 7:27 AM, Niklas Laxström niklas.laxstrom@gmail.com wrote:
The issue of how to use @since annotations recently came up in the code review. Those are essential for extension developers who want to target multiple MediaWiki versions with one codebase. I think we should come up a standard way to use those.
I think @since annotations are probably useless. You can't reliably tell if an extension will work on an old version without actually testing it on the old version, and if you do that, you can figure out what works by the error messages. Just because a method or class was present doesn't mean it worked the same way, so @since is not enough. It's got to be less work to just try it than to check every single one of the dozens or hundreds of methods you use for compatibility, too (which no one is going to do).
If you do want to find out if a method is in the version you're targeting, there's a very easy way: check out the branch in SVN and look in the file. Or use ViewVC. It's not really harder than looking in the source code. On the other hand, manually adding @since clutters the comments, makes that much less code fit on one screen, and will create zillions of cleanup commits (which we already have too many of).
So I think we shouldn't use @since at all, personally.
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On 15 August 2010 20:36, Aryeh Gregor Simetrical+wikilist@gmail.com wrote:
If you do want to find out if a method is in the version you're targeting, there's a very easy way: check out the branch in SVN and look in the file. Or use ViewVC. It's not really harder than looking in the source code. On the other hand, manually adding @since clutters the comments, makes that much less code fit on one screen, and will create zillions of cleanup commits (which we already have too many of).
While developing, I open the source file anyway to check the method name and order of parameters. Some people may use documentation for that. For both cases the @since tag is useful while opening the same file in different branches is waste of time. Same applies for ViewCV. You might not care about them, but how about the many extension developers, including me?
Moreover, I don't see a problem with cleanup commits. They are inevitable given our old and crufty codebase and lack of conventions in past. I don't believe this will introduce more of those, since usually only new methods are marked, only old ones only when needed.
So I think we shouldn't use @since at all, personally.
Since no other acceptable solution is proposed, I disagree.
-Niklas
wikitech-l@lists.wikimedia.org