Mailing-List: contact dev-help@camel.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@camel.apache.org
Received-SPF: pass (athena.apache.org: domain of hzbarcea@gmail.com designates
 209.85.161.173 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=content-type:mime-version:subject:from:in-reply-to:date
         :content-transfer-encoding:message-id:references:to:x-mailer;
        b=SbUw6YhCvfpFI6Ni/lI9eSRpA2FS8NSqAvK+OBZ8jz+ZrhdS65hPvz4U3cQq0EfsUz
         EOsDAodNgxk+tuTk/Nt5EKaUN9o0DieGbfo60HGbxhOLwYxyQ6gYozAktbrwatG9lspA
         hz7KEmtMmHw7G8yFHTmgMkECJyHsbWxMyoZDY=
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Apple Message framework v1081)
Subject: Re: snippet versioning
From: Hadrian Zbarcea <hzbarcea@gmail.com>
In-Reply-To: <05B2CCC9-E615-4CA4-9355-83CC3264554F@tataryn.net>
Date: Wed, 13 Oct 2010 16:57:33 -0400
Content-Transfer-Encoding: quoted-printable
Message-Id: <D706B0BE-0BBA-4F4C-9F46-3A5CA1B931DD@gmail.com>
References: <05B2CCC9-E615-4CA4-9355-83CC3264554F@tataryn.net>
To: dev@camel.apache.org

Hi Craig,

This is a good idea (and it has been discussed before). =46rom 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.=20
>=20
> 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. =20
>=20
> 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).
>=20
> 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.
>=20
> Thanks,
>=20
> Craig.
>=20
> --
> Craig Tataryn
> site: http://www.basementcoders.com/
> podcast: http://www.basementcoders.com/?feed=3Dpodcast
> itunes: http://itunes.apple.com/podcast/the-basement-coders
> irc: ThaDon on freenode #basementcoders, ##wicket, #papernapkin
> twitter: craiger
>=20