snippet versioning

[Craig Tataryn <cr...@tataryn.net>]

Just editing a few of the help documents and came across something.  The "{snippet}" examples tend to come directly from trunk, however it's a bit misleading for users if they are seeing examples which work against "the latest and greatest" but they are stuck on a release version.  A lot of "why isn't this working!!&&@!!! I copied the example right from the site" type questions arise. 

A lot of times, to compensate, the documentation will include "feature X available in versions Y.YY or later).   The only time this falls apart is if you have a feature which has changed between versions and the snippet of code shown in the documentation only works with the "trunk" or "SNAPSHOT" build.  

For instance the example for MultiPart processing using the Jetty component had a feature added to it (i.e. use of getName() on the DataHandler works properly as of version 2.5) So even though the MultiPart feature has worked since 2.3, some aspects in the example don't (I updated the documentation to point this fact out).

My question is, should we maybe only reference examples from the "current" release (i.e. can we use some type of variable in the {snippet} tag within the wiki to reference the proper branch to pull the code snippet from in SVN) by default?  Then if you want to point specifically at an example from another branch you can do so by specifying the branch explicitly.

Thanks,

Craig.

--
Craig Tataryn
site: http://www.basementcoders.com/
podcast: http://www.basementcoders.com/?feed=podcast
itunes: http://itunes.apple.com/podcast/the-basement-coders
irc: ThaDon on freenode #basementcoders, ##wicket, #papernapkin
twitter: craiger

Re: snippet versioning

[Hadrian Zbarcea <hz...@gmail.com>]

Hi Craig,

This is a good idea (and it has been discussed before). From my experience the issue is not with doing that, but maintaining the documentation. And I would suggest tags not branches, because that's what gets released.

When you document based on the trunk, the code most probably works... on the trunk, so it may not work with a previous release. When changing code, it's not always easy to know what test gets affected (if the test passes), let alone where in the wiki it's referenced. I'd love to find a workable solution for this.

Cheers
Hadrian


On Oct 13, 2010, at 3:45 PM, Craig Tataryn wrote:

> Just editing a few of the help documents and came across something.  The "{snippet}" examples tend to come directly from trunk, however it's a bit misleading for users if they are seeing examples which work against "the latest and greatest" but they are stuck on a release version.  A lot of "why isn't this working!!&&@!!! I copied the example right from the site" type questions arise. 
> 
> A lot of times, to compensate, the documentation will include "feature X available in versions Y.YY or later).   The only time this falls apart is if you have a feature which has changed between versions and the snippet of code shown in the documentation only works with the "trunk" or "SNAPSHOT" build.  
> 
> For instance the example for MultiPart processing using the Jetty component had a feature added to it (i.e. use of getName() on the DataHandler works properly as of version 2.5) So even though the MultiPart feature has worked since 2.3, some aspects in the example don't (I updated the documentation to point this fact out).
> 
> My question is, should we maybe only reference examples from the "current" release (i.e. can we use some type of variable in the {snippet} tag within the wiki to reference the proper branch to pull the code snippet from in SVN) by default?  Then if you want to point specifically at an example from another branch you can do so by specifying the branch explicitly.
> 
> Thanks,
> 
> Craig.
> 
> --
> Craig Tataryn
> site: http://www.basementcoders.com/
> podcast: http://www.basementcoders.com/?feed=podcast
> itunes: http://itunes.apple.com/podcast/the-basement-coders
> irc: ThaDon on freenode #basementcoders, ##wicket, #papernapkin
> twitter: craiger
>