You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by Deepal Jayasinghe <de...@opensource.lk> on 2006/03/21 08:13:28 UTC
[Axis2] Why do we have multiple versions of docs in xdocs
Hi all;
In the xdoc folder contains document for already released versions (0.93
, 0.94) and current version. And I dont think we need to keep multiple
doc folders inside xdocs for each versions, since we are not going to
change them once we do a release. In the meantime if we want to change
what we should do is take docs for SVN tag corresponding to that and
change that and commit those changes to WS-site.
And maintaining multiple docs folders is not going to be good idea when
we have much more versions. And other thing is it take my disk space
unnecessarily :)
If some new Axis2 user trying to get fresh SVN update then does that
guy need to have document for older version ? , I think he does not need
and he only need docs for the current code base.
So shall we only keep doc for the latest revision in side xdocs and keep
older versions inside ws-site.
We have to have docs in the site since some one is still using older
version then he has to have a way of reading old docs.
Comments ....
--
Thanks,
Deepal
................................................................
~Future is Open~
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Ajith Ranabahu <aj...@gmail.com>.
Hi all,
Yes I agree that the person who does it should have a major part in
deciding 'how' to do it (and ofcourse Chatra is doing a great job -
no doubts about it) But if that person chooses a particularly complex
and not-very-appropriate solution I think we, as a community should be
pointing them in the right way, at least the way that the community
feels the right way.
Having said that, I am not really happy about maintaining the older
versions inside the xdocs folder. I as a user would love to see a
clean xdocs folder when I do a checkout of the source (I should say
I'm not talking about the regular axis2 developer guy who already has
a source checkout in his computer. This is the newbie who has the
curiosity to look at the latest source) . I would not appreciate
having documents of two previous releases in my current source tree
(ok what is the use of it anyway?).
If this is an issue with maintaining older documentation, well SVN
branching is there to help you. The exact reasoning for having the
branching capability in a versioning system is that.
The other thing is that none of the other projects go into this mess
(if it's thought as a mess). Almost all of them maintain only the docs
that are relevant to the current source and thats it (at least the
ones I know)
I'm not gonna drag this further but for me the bottom line is that it
is far better to have only the latest docs inside the SVN. If you want
to maintain older docs, fine, then use the branch!
Ajith
On 3/21/06, Eran Chinthaka <ch...@opensource.lk> wrote:
> I hope I asked this question sometime back and no one answered. Anyway,
> here we go.
>
> Deepal Jayasinghe wrote:
> > Hi all;
> >
> > In the xdoc folder contains document for already released versions (0.93
> > , 0.94) and current version. And I dont think we need to keep multiple
> > doc folders inside xdocs for each versions, since we are not going to
> > change them once we do a release.
> How can you say that ? From my experience, even after releases we do
> change the documents and generate the site. Chatra know about this
> better than me.
> And you can not freeze the site after a release, and there is no
> connection between them.
> > In the meantime if we want to change
> > what we should do is take docs for SVN tag corresponding to that and
> > change that and commit those changes to WS-site.
> >
> This is very simple to say. But people who actually do changes knows how
> difficult this is.
>
> Think about following scenario.
> If I want to change a document in 0.94. I need to checkout only that and
> change it. And the questions are as follows
>
> 1. which version I should checkout, as there are continuing changes to
> the documents even after a release, which we MUST agree.
> 2. How can I re-build the site ? For me to rebuild the site, I must have
> all the docs around.
>
> Do not put this argument away saying how frequent you change docs in
> past releases. Chatra and her commitse are proofs for that.
>
> Think about this scenario as well.
> Now I want to change a particular document, or may be change the
> navigation pane and re-build the site. Do you want me to checkout all
> the document versions and then re-build the site, as site contains old
> docs ? D you think someone will do it ?
>
> > And maintaining multiple docs folders is not going to be good idea when
> > we have much more versions. And other thing is it take my disk space
> > unnecessarily :)
> >
> ok, how much of diskspace you are talking about here ? Be realistic. How
> come you become so conservative about your disk space all of a sudden
> :-) .
> > If some new Axis2 user trying to get fresh SVN update then does that
> > guy need to have document for older version ? , I think he does not need
> > and he only need docs for the current code base.
> >
> Hmm, how frequent is this scenario. Do you think the frequency of
> someone getting a clean checkout is higher than Chatra or anyone
> updating the docs. I don't think so. How many times you took fresh
> updates, during last 3 months, and how many commits have gone to 0.94
> docs ?
> > So shall we only keep doc for the latest revision in side xdocs and keep
> > older versions inside ws-site.
> >
>
>
> Come on. My feeling is let the person who actually does it decide it.
> Thats our practice so far. Mostly Chatra maintains our documents.
> AFAIK, she is doing very good stuff. Its unfair if we jump in and make
> here job difficult.
>
> Believe me you gain nothing by removing these docs. I'm ok if we can
> keep at least two versions back. But for removing all the docs, except
> latest, I'm 0- (as I hate to -1 an issue).
>
> Regards,
> Chinthaka
>
>
>
--
Ajith Ranabahu
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Deepal Jayasinghe <de...@opensource.lk>.
+1 :)
Eran Chinthaka wrote:
> Ok, time to compromise ;-)
>
> Lets maintain two versions of the documents inside the xdocs. One with
> the *released* version of docs and the other with *latest *version of
> the docs.
>
> And lets have all the versions of the documents in the site. *BUT, *we
> will update only the documents of the last release. So the older
> documents will be sort of archived, but the links will never change.
>
> Can we all agree to this ?
>
> This is my +1.
>
> -- Chinthaka
>
>
--
Thanks,
Deepal
................................................................
~Future is Open~
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Ruchith Fernando <ru...@gmail.com>.
+1 from me to maintain 'released' and 'latest' versions of documents
in the SVN head.
Thanks,
Ruchith
On 3/21/06, Eran Chinthaka <ch...@opensource.lk> wrote:
> Ok, time to compromise ;-)
>
> Lets maintain two versions of the documents inside the xdocs. One with
> the *released* version of docs and the other with *latest *version of
> the docs.
>
> And lets have all the versions of the documents in the site. *BUT, *we
> will update only the documents of the last release. So the older
> documents will be sort of archived, but the links will never change.
>
> Can we all agree to this ?
>
> This is my +1.
>
> -- Chinthaka
>
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Chatra Nakkawita <ch...@gmail.com>.
hey ajith,
you did hear my reply...may be not on mail. but i did +1 chinthaka's
solution.
anyways for the record.... here goes:
one thing i have to make clear is that once a release has been made and the
code frozen it is very impractical to think that you can freeze the
documentaion with it. may be you can do that if you are planning to actually
make the release one week after the code freeze or something like that.
the only way u can even mention about a critical errors on the release
(code) is through documentaion. so it is unfair and unrealistic to think
that u can freeze documentaion with a release. the docs of the latest
released should be easily available for anyone to commit and make a
correction or critical improvement.
we have a web site to give ppl information and instructions on product,
therefore any documentaion/content that goes on it is subjected to
improvements and error corrections. more or less it is the right of the
reader/audience to get accurate & user friendly documentaion.
or what would u suggest have another page carrying infor on errors of
product/project documentaion that's published on site.
you must give freedom to correct errors on docs published on site.
i agree that carrying previous versions on xdocs will make a check out
heavy. so like v agreed (chinthaka's last mail) the compromise will be to
have docs for latest version released and the docs of the version v are
currently working on (for next release). that makes great sense to me.
you must include the docs of latest released version in xdocs because it is
going to be subjected to error corrections and improvements after the
release as i mentioned earlier. and for obvious reasons v need to have docs
of the next release v are working on.
so lets just have 2 dirs containing docs of two release (latest released and
next to be released)......it sounds pretty practical and fair enough to
everyone.
and on the site.....i agree with sanjiva....nothing should be removed from
site. URLs need to be static cos they are linked to from so many other
sites. so lets have an archive for the previous releases documentaio and
another link for current release (latest released)..... and if possible
another link for docs which are for the next upcoming relase (that's
optional).
i will be updting site for latest released docs and upcoming release docs
so there's my answer
thanks & regards,
Chatra
On 3/22/06, Ajith Ranabahu <aj...@gmail.com> wrote:
>
> ok,
> I guess I went overboard with my theory of strictly maintaining the
> current docs in SVN (That's no reason to pull out that old builder
> extension thing anyway :( ) but I guess I'm more biased to doing
> things the right way rather than the easy way (which is unfortunately
> not the same and sometimes the 'right' way is very subjective)
> I'm (reluctantly) ok with having two versions of documents in the
> xdocs however what I'm trying to convince the people is that it's not
> the elegant solution. With all this technology around us (SVN,maven,
> ant) we should be able to find a better solution than this :)
> However I'm not maintaining the docs so it's not my call. May it be an
> ugly solution, but if it suits the one who'll be really doing the
> work, then let it be. Having said that we are yet to hear the opinion
> of Chathra on this and I would say that is the conclusion of this
> thread
>
> Ajith
>
> On 3/21/06, Eran Chinthaka <ch...@opensource.lk> wrote:
> > I hope we can apply our "builder extensions" theory here, but
> > unfortunately for the same person :-D
> >
> > (for those who doesn't know what this builder extensions theory is,
> > please search for the mails of Axis2 during its start up days)
> >
> > -- Chinthaka
> >
> > Ajith Ranabahu wrote:
> > > Hi all,
> > > Ok I'm also +1 to the compromise but I have a small issue to be
> clarified.
> > > Once a release is out we do a SVN tag (and I've been told that tags
> > > automatically become branches, of which I'm not really sure about - If
> > > not lets say we always start a branch after a tag which seems to be
> > > the right thing to do if there are continuous changes). The idea of
> > > the tag is a convenient way of retrieving the relevant version later.
> > > However if we do the updates on the main tree and not commit the same
> > > changes to the branches , the source retrieved from that branch will
> > > be inconsistent!
> > > I remember a cool feature is VSS (ok - I used to work with MSFT
> > > software sometime earlier :)) where a source file could be shared in
> > > two locations (more like a symlink thing). If we do have something
> > > like that in SVN that'd solve our problem
> > >
> > > Ajith
> > >
> > > On 3/21/06, robert lazarski <ro...@gmail.com> wrote:
> > >
> > >> "Damn, I was going to enjoy giving boxing gloves to see open source
> > >> developers fight about documentation!!!!!!!!!!!"
> > >>
> > >> Or a soccer ball, since the world cup is approaching. ;-) +1 to a
> good
> > >> compromise.
> > >>
> > >> Robert
> > >> http://www.braziloutsource.com/
> > >>
> > >>
> > >> On 3/21/06, Sanjiva Weerawarana < sanjiva@opensource.lk> wrote:
> > >>
> > >>> Cool :) +1.
> > >>>
> > >>> Damn, I was going to enjoy giving boxing gloves to see open source
> > >>> developers fight about documentation!!!!!!!!!!!
> > >>>
> > >>> Sanjiva.
> > >>>
> > >>> On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
> > >>>
> > >>>> Ok, time to compromise ;-)
> > >>>>
> > >>>> Lets maintain two versions of the documents inside the xdocs. One
> with
> > >>>> the *released* version of docs and the other with *latest *version
> of
> > >>>> the docs.
> > >>>>
> > >>>> And lets have all the versions of the documents in the site. *BUT,
> *we
> > >>>> will update only the documents of the last release. So the older
> > >>>> documents will be sort of archived, but the links will never
> change.
> > >>>>
> > >>>> Can we all agree to this ?
> > >>>>
> > >>>> This is my +1.
> > >>>>
> > >>>> -- Chinthaka
> > >>>>
> > >>>
> > >>
> > >
> > >
> > > --
> > > Ajith Ranabahu
> > >
> > >
> >
> >
>
>
> --
> Ajith Ranabahu
>
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Ajith Ranabahu <aj...@gmail.com>.
ok,
I guess I went overboard with my theory of strictly maintaining the
current docs in SVN (That's no reason to pull out that old builder
extension thing anyway :( ) but I guess I'm more biased to doing
things the right way rather than the easy way (which is unfortunately
not the same and sometimes the 'right' way is very subjective)
I'm (reluctantly) ok with having two versions of documents in the
xdocs however what I'm trying to convince the people is that it's not
the elegant solution. With all this technology around us (SVN,maven,
ant) we should be able to find a better solution than this :)
However I'm not maintaining the docs so it's not my call. May it be an
ugly solution, but if it suits the one who'll be really doing the
work, then let it be. Having said that we are yet to hear the opinion
of Chathra on this and I would say that is the conclusion of this
thread
Ajith
On 3/21/06, Eran Chinthaka <ch...@opensource.lk> wrote:
> I hope we can apply our "builder extensions" theory here, but
> unfortunately for the same person :-D
>
> (for those who doesn't know what this builder extensions theory is,
> please search for the mails of Axis2 during its start up days)
>
> -- Chinthaka
>
> Ajith Ranabahu wrote:
> > Hi all,
> > Ok I'm also +1 to the compromise but I have a small issue to be clarified.
> > Once a release is out we do a SVN tag (and I've been told that tags
> > automatically become branches, of which I'm not really sure about - If
> > not lets say we always start a branch after a tag which seems to be
> > the right thing to do if there are continuous changes). The idea of
> > the tag is a convenient way of retrieving the relevant version later.
> > However if we do the updates on the main tree and not commit the same
> > changes to the branches , the source retrieved from that branch will
> > be inconsistent!
> > I remember a cool feature is VSS (ok - I used to work with MSFT
> > software sometime earlier :)) where a source file could be shared in
> > two locations (more like a symlink thing). If we do have something
> > like that in SVN that'd solve our problem
> >
> > Ajith
> >
> > On 3/21/06, robert lazarski <ro...@gmail.com> wrote:
> >
> >> "Damn, I was going to enjoy giving boxing gloves to see open source
> >> developers fight about documentation!!!!!!!!!!!"
> >>
> >> Or a soccer ball, since the world cup is approaching. ;-) +1 to a good
> >> compromise.
> >>
> >> Robert
> >> http://www.braziloutsource.com/
> >>
> >>
> >> On 3/21/06, Sanjiva Weerawarana < sanjiva@opensource.lk> wrote:
> >>
> >>> Cool :) +1.
> >>>
> >>> Damn, I was going to enjoy giving boxing gloves to see open source
> >>> developers fight about documentation!!!!!!!!!!!
> >>>
> >>> Sanjiva.
> >>>
> >>> On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
> >>>
> >>>> Ok, time to compromise ;-)
> >>>>
> >>>> Lets maintain two versions of the documents inside the xdocs. One with
> >>>> the *released* version of docs and the other with *latest *version of
> >>>> the docs.
> >>>>
> >>>> And lets have all the versions of the documents in the site. *BUT, *we
> >>>> will update only the documents of the last release. So the older
> >>>> documents will be sort of archived, but the links will never change.
> >>>>
> >>>> Can we all agree to this ?
> >>>>
> >>>> This is my +1.
> >>>>
> >>>> -- Chinthaka
> >>>>
> >>>
> >>
> >
> >
> > --
> > Ajith Ranabahu
> >
> >
>
>
--
Ajith Ranabahu
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Eran Chinthaka <ch...@opensource.lk>.
I hope we can apply our "builder extensions" theory here, but
unfortunately for the same person :-D
(for those who doesn't know what this builder extensions theory is,
please search for the mails of Axis2 during its start up days)
-- Chinthaka
Ajith Ranabahu wrote:
> Hi all,
> Ok I'm also +1 to the compromise but I have a small issue to be clarified.
> Once a release is out we do a SVN tag (and I've been told that tags
> automatically become branches, of which I'm not really sure about - If
> not lets say we always start a branch after a tag which seems to be
> the right thing to do if there are continuous changes). The idea of
> the tag is a convenient way of retrieving the relevant version later.
> However if we do the updates on the main tree and not commit the same
> changes to the branches , the source retrieved from that branch will
> be inconsistent!
> I remember a cool feature is VSS (ok - I used to work with MSFT
> software sometime earlier :)) where a source file could be shared in
> two locations (more like a symlink thing). If we do have something
> like that in SVN that'd solve our problem
>
> Ajith
>
> On 3/21/06, robert lazarski <ro...@gmail.com> wrote:
>
>> "Damn, I was going to enjoy giving boxing gloves to see open source
>> developers fight about documentation!!!!!!!!!!!"
>>
>> Or a soccer ball, since the world cup is approaching. ;-) +1 to a good
>> compromise.
>>
>> Robert
>> http://www.braziloutsource.com/
>>
>>
>> On 3/21/06, Sanjiva Weerawarana < sanjiva@opensource.lk> wrote:
>>
>>> Cool :) +1.
>>>
>>> Damn, I was going to enjoy giving boxing gloves to see open source
>>> developers fight about documentation!!!!!!!!!!!
>>>
>>> Sanjiva.
>>>
>>> On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
>>>
>>>> Ok, time to compromise ;-)
>>>>
>>>> Lets maintain two versions of the documents inside the xdocs. One with
>>>> the *released* version of docs and the other with *latest *version of
>>>> the docs.
>>>>
>>>> And lets have all the versions of the documents in the site. *BUT, *we
>>>> will update only the documents of the last release. So the older
>>>> documents will be sort of archived, but the links will never change.
>>>>
>>>> Can we all agree to this ?
>>>>
>>>> This is my +1.
>>>>
>>>> -- Chinthaka
>>>>
>>>
>>
>
>
> --
> Ajith Ranabahu
>
>
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Ajith Ranabahu <aj...@gmail.com>.
Hi all,
Ok I'm also +1 to the compromise but I have a small issue to be clarified.
Once a release is out we do a SVN tag (and I've been told that tags
automatically become branches, of which I'm not really sure about - If
not lets say we always start a branch after a tag which seems to be
the right thing to do if there are continuous changes). The idea of
the tag is a convenient way of retrieving the relevant version later.
However if we do the updates on the main tree and not commit the same
changes to the branches , the source retrieved from that branch will
be inconsistent!
I remember a cool feature is VSS (ok - I used to work with MSFT
software sometime earlier :)) where a source file could be shared in
two locations (more like a symlink thing). If we do have something
like that in SVN that'd solve our problem
Ajith
On 3/21/06, robert lazarski <ro...@gmail.com> wrote:
>
> "Damn, I was going to enjoy giving boxing gloves to see open source
> developers fight about documentation!!!!!!!!!!!"
>
> Or a soccer ball, since the world cup is approaching. ;-) +1 to a good
> compromise.
>
> Robert
> http://www.braziloutsource.com/
>
>
> On 3/21/06, Sanjiva Weerawarana < sanjiva@opensource.lk> wrote:
> > Cool :) +1.
> >
> > Damn, I was going to enjoy giving boxing gloves to see open source
> > developers fight about documentation!!!!!!!!!!!
> >
> > Sanjiva.
> >
> > On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
> > > Ok, time to compromise ;-)
> > >
> > > Lets maintain two versions of the documents inside the xdocs. One with
> > > the *released* version of docs and the other with *latest *version of
> > > the docs.
> > >
> > > And lets have all the versions of the documents in the site. *BUT, *we
> > > will update only the documents of the last release. So the older
> > > documents will be sort of archived, but the links will never change.
> > >
> > > Can we all agree to this ?
> > >
> > > This is my +1.
> > >
> > > -- Chinthaka
> >
> >
>
>
--
Ajith Ranabahu
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Chatra Nakkawita <ch...@gmail.com>.
"Or a soccer ball, since the world cup is approaching. "
yapee.....u got a die hard soccer fan here.
yes....+1 for compromise. on a more prcatical aspect pl do understand you
cannot freeze documentation like you freeze code.
chatra
On 3/21/06, robert lazarski <ro...@gmail.com> wrote:
>
>
> "Damn, I was going to enjoy giving boxing gloves to see open source
> developers fight about documentation!!!!!!!!!!!"
>
> Or a soccer ball, since the world cup is approaching. ;-) +1 to a good
> compromise.
>
> Robert
> http://www.braziloutsource.com/
>
>
> On 3/21/06, Sanjiva Weerawarana < sanjiva@opensource.lk> wrote:
> >
> > Cool :) +1.
> >
> > Damn, I was going to enjoy giving boxing gloves to see open source
> > developers fight about documentation!!!!!!!!!!!
> >
> > Sanjiva.
> >
> > On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
> > > Ok, time to compromise ;-)
> > >
> > > Lets maintain two versions of the documents inside the xdocs. One with
> >
> > > the *released* version of docs and the other with *latest *version of
> > > the docs.
> > >
> > > And lets have all the versions of the documents in the site. *BUT, *we
> > > will update only the documents of the last release. So the older
> > > documents will be sort of archived, but the links will never change.
> > >
> > > Can we all agree to this ?
> > >
> > > This is my +1.
> > >
> > > -- Chinthaka
> >
> >
>
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by robert lazarski <ro...@gmail.com>.
"Damn, I was going to enjoy giving boxing gloves to see open source
developers fight about documentation!!!!!!!!!!!"
Or a soccer ball, since the world cup is approaching. ;-) +1 to a good
compromise.
Robert
http://www.braziloutsource.com/
On 3/21/06, Sanjiva Weerawarana <sa...@opensource.lk> wrote:
>
> Cool :) +1.
>
> Damn, I was going to enjoy giving boxing gloves to see open source
> developers fight about documentation!!!!!!!!!!!
>
> Sanjiva.
>
> On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
> > Ok, time to compromise ;-)
> >
> > Lets maintain two versions of the documents inside the xdocs. One with
> > the *released* version of docs and the other with *latest *version of
> > the docs.
> >
> > And lets have all the versions of the documents in the site. *BUT, *we
> > will update only the documents of the last release. So the older
> > documents will be sort of archived, but the links will never change.
> >
> > Can we all agree to this ?
> >
> > This is my +1.
> >
> > -- Chinthaka
>
>
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Chamil Thanthrimudalige <ch...@opensource.lk>.
:-)
Well 2 versions seems to be an ok middle ground. +1 from me too.
Chamil
On Mar 21, 2006, at 5:27 PM, Sanjiva Weerawarana wrote:
> Cool :) +1.
>
> Damn, I was going to enjoy giving boxing gloves to see open source
> developers fight about documentation!!!!!!!!!!!
>
> Sanjiva.
>
> On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
>> Ok, time to compromise ;-)
>>
>> Lets maintain two versions of the documents inside the xdocs. One
>> with
>> the *released* version of docs and the other with *latest *version of
>> the docs.
>>
>> And lets have all the versions of the documents in the site. *BUT,
>> *we
>> will update only the documents of the last release. So the older
>> documents will be sort of archived, but the links will never change.
>>
>> Can we all agree to this ?
>>
>> This is my +1.
>>
>> -- Chinthaka
>
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
Cool :) +1.
Damn, I was going to enjoy giving boxing gloves to see open source
developers fight about documentation!!!!!!!!!!!
Sanjiva.
On Tue, 2006-03-21 at 16:25 +0600, Eran Chinthaka wrote:
> Ok, time to compromise ;-)
>
> Lets maintain two versions of the documents inside the xdocs. One with
> the *released* version of docs and the other with *latest *version of
> the docs.
>
> And lets have all the versions of the documents in the site. *BUT, *we
> will update only the documents of the last release. So the older
> documents will be sort of archived, but the links will never change.
>
> Can we all agree to this ?
>
> This is my +1.
>
> -- Chinthaka
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Eran Chinthaka <ch...@opensource.lk>.
Ok, time to compromise ;-)
Lets maintain two versions of the documents inside the xdocs. One with
the *released* version of docs and the other with *latest *version of
the docs.
And lets have all the versions of the documents in the site. *BUT, *we
will update only the documents of the last release. So the older
documents will be sort of archived, but the links will never change.
Can we all agree to this ?
This is my +1.
-- Chinthaka
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Deepal Jayasinghe <de...@opensource.lk>.
hmmmm , I do not want to start a war :)
Eran Chinthaka wrote:
> I hope I asked this question sometime back and no one answered.
> Anyway, here we go.
>
> Deepal Jayasinghe wrote:
>
>> Hi all;
>>
>> In the xdoc folder contains document for already released versions (0.93
>> , 0.94) and current version. And I dont think we need to keep multiple
>> doc folders inside xdocs for each versions, since we are not going to
>> change them once we do a release.
>
> How can you say that ? From my experience, even after releases we do
> change the documents and generate the site. Chatra know about this
> better than me.
> And you can not freeze the site after a release, and there is no
> connection between them.
I totally agree that if we found some bugs in old document we have to
fix them , but that does not really require to have old docs in xdoc
folder if we have some other ways of doing that. (take update from SVN
branch corresponding to that version then build the site and put the
docs in to corresponding doc folder in ws-site , I know in site we keep
different folder for each version)
>>
>> what we should do is take docs for SVN tag corresponding to that and
>> change that and commit those changes to WS-site.
>>
>
> This is very simple to say. But people who actually do changes knows
> how difficult this is.Think about following scenario.
> If I want to change a document in 0.94. I need to checkout only that
> and change it. And the questions are as follows
>
> 1. which version I should checkout, as there are continuing changes to
> the documents even after a release, which we MUST agree.
you have to get the SVN branch corresponding to that version and change
that :)
> 2. How can I re-build the site ? For me to rebuild the site, I must
> have all the docs around.
You dont need to have old the docs around you when you building the site
, but when you get a check out you will have everything that you require
to build the site for that vresion, and the site you are building not
going to completely replace the existing site.
>
> Do not put this argument away saying how frequent you change docs in
> past releases. Chatra and her commitse are proofs for that.
>
> Think about this scenario as well.
> Now I want to change a particular document, or may be change the
> navigation pane and re-build the site. Do you want me to checkout all
> the document versions and then re-build the site, as site contains old
> docs ? D you think someone will do it ?
if we change navigation page then old document will be just a link from
navigation pane , in the current site it is.
>
>> And maintaining multiple docs folders is not going to be good idea when
>> we have much more versions. And other thing is it take my disk space
>> unnecessarily :)
>>
>
> ok, how much of diskspace you are talking about here ? Be realistic.
> How come you become so conservative about your disk space all of a
> sudden :-) .
I am not worry about too much , but once we have few more version , then
that will be an issue :)
>> If some new Axis2 user trying to get fresh SVN update then does that
>> guy need to have document for older version ? , I think he does not need
>> and he only need docs for the current code base.
>>
>
> Hmm, how frequent is this scenario. Do you think the frequency of
> someone getting a clean checkout is higher than Chatra or anyone
> updating the docs. I don't think so. How many times you took fresh
> updates, during last 3 months, and how many commits have gone to 0.94
> docs ?
updating the docs is not the problem here , updating old docs is the
problem
yes Chathra is doing changes on 0.94 but you know it is the current
version , and I am not sure she has done many changes to 0.93 docs.
>> So shall we only keep doc for the latest revision in side xdocs and keep
>> older versions inside ws-site.
>>
>
>
>
> Come on. My feeling is let the person who actually does it decide it.
> Thats our practice so far. Mostly Chatra maintains our documents.
> AFAIK, she is doing very good stuff. Its unfair if we jump in and make
> here job difficult.
1000 time agree with you.
>
> Believe me you gain nothing by removing these docs. I'm ok if we can
> keep at least two versions back. But for removing all the docs, except
> latest, I'm 0- (as I hate to -1 an issue).
>
> Regards,
> Chinthaka
>
>
>
>
--
Thanks,
Deepal
................................................................
~Future is Open~
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Sanjiva Weerawarana <sa...@opensource.lk>.
On Tue, 2006-03-21 at 14:33 +0600, Chamil Thanthrimudalige wrote:
> Hi,
>
> I think we can make a better decision if we are clear about Apache
> policy about maintaining docs for older revisions [Before a 1.0
> version and after]. So can some one jump in an enlighten us on what
> is the policy for dealing with old docs.
As usual, there's no ASF policy ... we set our own policy.
So, what do we want? ;-)
Sanjiva.
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Chamil Thanthrimudalige <ch...@opensource.lk>.
Hi,
I think we can make a better decision if we are clear about Apache
policy about maintaining docs for older revisions [Before a 1.0
version and after]. So can some one jump in an enlighten us on what
is the policy for dealing with old docs.
Best Regards,
Chamil Thanthrimudalige
On Mar 21, 2006, at 2:15 PM, Eran Chinthaka wrote:
> I hope I asked this question sometime back and no one answered.
> Anyway, here we go.
>
> Deepal Jayasinghe wrote:
>> Hi all;
>>
>> In the xdoc folder contains document for already released versions
>> (0.93
>> , 0.94) and current version. And I dont think we need to keep
>> multiple
>> doc folders inside xdocs for each versions, since we are not going to
>> change them once we do a release.
> How can you say that ? From my experience, even after releases we
> do change the documents and generate the site. Chatra know about
> this better than me.
> And you can not freeze the site after a release, and there is no
> connection between them.
>> In the meantime if we want to change
>> what we should do is take docs for SVN tag corresponding to that and
>> change that and commit those changes to WS-site.
>>
> This is very simple to say. But people who actually do changes
> knows how difficult this is.
>
> Think about following scenario.
> If I want to change a document in 0.94. I need to checkout only
> that and change it. And the questions are as follows
>
> 1. which version I should checkout, as there are continuing changes
> to the documents even after a release, which we MUST agree.
> 2. How can I re-build the site ? For me to rebuild the site, I must
> have all the docs around.
>
> Do not put this argument away saying how frequent you change docs
> in past releases. Chatra and her commitse are proofs for that.
>
> Think about this scenario as well.
> Now I want to change a particular document, or may be change the
> navigation pane and re-build the site. Do you want me to checkout
> all the document versions and then re-build the site, as site
> contains old docs ? D you think someone will do it ?
>
>> And maintaining multiple docs folders is not going to be good idea
>> when
>> we have much more versions. And other thing is it take my disk space
>> unnecessarily :)
>>
> ok, how much of diskspace you are talking about here ? Be
> realistic. How come you become so conservative about your disk
> space all of a sudden :-) .
>> If some new Axis2 user trying to get fresh SVN update then does that
>> guy need to have document for older version ? , I think he does
>> not need
>> and he only need docs for the current code base.
>>
> Hmm, how frequent is this scenario. Do you think the frequency of
> someone getting a clean checkout is higher than Chatra or anyone
> updating the docs. I don't think so. How many times you took fresh
> updates, during last 3 months, and how many commits have gone to
> 0.94 docs ?
>> So shall we only keep doc for the latest revision in side xdocs
>> and keep
>> older versions inside ws-site.
>>
>
>
> Come on. My feeling is let the person who actually does it decide
> it. Thats our practice so far. Mostly Chatra maintains our
> documents. AFAIK, she is doing very good stuff. Its unfair if we
> jump in and make here job difficult.
>
> Believe me you gain nothing by removing these docs. I'm ok if we
> can keep at least two versions back. But for removing all the docs,
> except latest, I'm 0- (as I hate to -1 an issue).
>
> Regards,
> Chinthaka
>
>
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Eran Chinthaka <ch...@opensource.lk>.
I hope I asked this question sometime back and no one answered. Anyway,
here we go.
Deepal Jayasinghe wrote:
> Hi all;
>
> In the xdoc folder contains document for already released versions (0.93
> , 0.94) and current version. And I dont think we need to keep multiple
> doc folders inside xdocs for each versions, since we are not going to
> change them once we do a release.
How can you say that ? From my experience, even after releases we do
change the documents and generate the site. Chatra know about this
better than me.
And you can not freeze the site after a release, and there is no
connection between them.
> In the meantime if we want to change
> what we should do is take docs for SVN tag corresponding to that and
> change that and commit those changes to WS-site.
>
This is very simple to say. But people who actually do changes knows how
difficult this is.
Think about following scenario.
If I want to change a document in 0.94. I need to checkout only that and
change it. And the questions are as follows
1. which version I should checkout, as there are continuing changes to
the documents even after a release, which we MUST agree.
2. How can I re-build the site ? For me to rebuild the site, I must have
all the docs around.
Do not put this argument away saying how frequent you change docs in
past releases. Chatra and her commitse are proofs for that.
Think about this scenario as well.
Now I want to change a particular document, or may be change the
navigation pane and re-build the site. Do you want me to checkout all
the document versions and then re-build the site, as site contains old
docs ? D you think someone will do it ?
> And maintaining multiple docs folders is not going to be good idea when
> we have much more versions. And other thing is it take my disk space
> unnecessarily :)
>
ok, how much of diskspace you are talking about here ? Be realistic. How
come you become so conservative about your disk space all of a sudden
:-) .
> If some new Axis2 user trying to get fresh SVN update then does that
> guy need to have document for older version ? , I think he does not need
> and he only need docs for the current code base.
>
Hmm, how frequent is this scenario. Do you think the frequency of
someone getting a clean checkout is higher than Chatra or anyone
updating the docs. I don't think so. How many times you took fresh
updates, during last 3 months, and how many commits have gone to 0.94
docs ?
> So shall we only keep doc for the latest revision in side xdocs and keep
> older versions inside ws-site.
>
Come on. My feeling is let the person who actually does it decide it.
Thats our practice so far. Mostly Chatra maintains our documents.
AFAIK, she is doing very good stuff. Its unfair if we jump in and make
here job difficult.
Believe me you gain nothing by removing these docs. I'm ok if we can
keep at least two versions back. But for removing all the docs, except
latest, I'm 0- (as I hate to -1 an issue).
Regards,
Chinthaka
Re: [Axis2] Why do we have multiple versions of docs in xdocs
Posted by Eran Chinthaka <ch...@opensource.lk>.
I hope I asked this question sometime back and no one answered. Anyway,
here we go.
Deepal Jayasinghe wrote:
> Hi all;
>
> In the xdoc folder contains document for already released versions (0.93
> , 0.94) and current version. And I dont think we need to keep multiple
> doc folders inside xdocs for each versions, since we are not going to
> change them once we do a release.
How can you say that ? From my experience, even after releases we do
change the documents and generate the site. Chatra know about this
better than me.
And you can not freeze the site after a release, and there is no
connection between them.
> In the meantime if we want to change
> what we should do is take docs for SVN tag corresponding to that and
> change that and commit those changes to WS-site.
>
This is very simple to say. But people who actually do changes knows how
difficult this is.
Think about following scenario.
If I want to change a document in 0.94. I need to checkout only that and
change it. And the questions are as follows
1. which version I should checkout, as there are continuing changes to
the documents even after a release, which we MUST agree.
2. How can I re-build the site ? For me to rebuild the site, I must have
all the docs around.
Do not put this argument away saying how frequent you change docs in
past releases. Chatra and her commitse are proofs for that.
Think about this scenario as well.
Now I want to change a particular document, or may be change the
navigation pane and re-build the site. Do you want me to checkout all
the document versions and then re-build the site, as site contains old
docs ? D you think someone will do it ?
> And maintaining multiple docs folders is not going to be good idea when
> we have much more versions. And other thing is it take my disk space
> unnecessarily :)
>
ok, how much of diskspace you are talking about here ? Be realistic. How
come you become so conservative about your disk space all of a sudden
:-) .
> If some new Axis2 user trying to get fresh SVN update then does that
> guy need to have document for older version ? , I think he does not need
> and he only need docs for the current code base.
>
Hmm, how frequent is this scenario. Do you think the frequency of
someone getting a clean checkout is higher than Chatra or anyone
updating the docs. I don't think so. How many times you took fresh
updates, during last 3 months, and how many commits have gone to 0.94
docs ?
> So shall we only keep doc for the latest revision in side xdocs and keep
> older versions inside ws-site.
>
Come on. My feeling is let the person who actually does it decide it.
Thats our practice so far. Mostly Chatra maintains our documents. Its
unfair if we jump in and make here job difficult.
Believe me you gain nothing by removing these docs. I'm ok if we can
keep at least two versions back. But for removing all the docs, except
latest, I'm 0- (as I hate to -1 an issue).
Regards,
Chinthaka