camel-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hadrian Zbarcea <>
Subject Re: snippet versioning
Date Wed, 13 Oct 2010 20:57:33 GMT
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.


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:
> podcast:
> itunes:
> irc: ThaDon on freenode #basementcoders, ##wicket, #papernapkin
> twitter: craiger

View raw message