You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@karaf.apache.org by Jean-Baptiste Onofré <jb...@nanthrax.net> on 2011/06/17 09:18:34 UTC
Karaf first birthday concall minute notes
Hi all,
Following our yesterday concall, I wrote down the minute notes:
https://cwiki.apache.org/confluence/display/KARAF/Apache+Karaf+First+Birthday+Meeting+%282011-06-16%29
Feel free to update and change it.
As I said yesterday, I will start to work on the Karaf roadmap page and
Karaf architecture/implementation draft.
I think that these pages should be easily visible by the website visitor.
That's why I propose to write it into the Karaf website and not the wiki.
WDYT ?
Thanks
Regards
JB
Re: Karaf first birthday concall minute notes
Posted by Achim Nierbeck <bc...@googlemail.com>.
Hi JB,
+1 for beeing visible for all visitors.
How about "embedding" this or maybe other pages from Wiki inside the
std.Karaf pages.
Regards, Achim
2011/6/17 Jean-Baptiste Onofré <jb...@nanthrax.net>:
> Hi all,
>
> Following our yesterday concall, I wrote down the minute notes:
>
> https://cwiki.apache.org/confluence/display/KARAF/Apache+Karaf+First+Birthday+Meeting+%282011-06-16%29
>
> Feel free to update and change it.
>
> As I said yesterday, I will start to work on the Karaf roadmap page and
> Karaf architecture/implementation draft.
>
> I think that these pages should be easily visible by the website visitor.
> That's why I propose to write it into the Karaf website and not the wiki.
>
> WDYT ?
>
> Thanks
> Regards
> JB
>
--
--
*Achim Nierbeck*
Apache Karaf <http://karaf.apache.org/> Committer & PMC
OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/>
Committer & Project Lead
Re: Karaf first birthday concall minute notes
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
On the wiki, we didn't update the content (deprecated).
The website is OK.
Regards
JB
On 06/17/2011 09:49 AM, Achim Nierbeck wrote:
> JB,
>
> +1 for wiki pages as children of the "cap" page :-)
>
> btw. why is the documentation still showing the 2.1.99-SNAPSHOT
> instead of 2.2.1-SNAPSHOT?
>
> regards, Achim
>
> 2011/6/17 Jean-Baptiste Onofré<jb...@nanthrax.net>:
>> Agree Andreas,
>>
>> I think that:
>> - link to the wiki "cap" page in the community area of the website
>> - wiki pages as children of the "cap" page
>>
>> is the most efficient way.
>>
>> Regards
>> JB
>>
>> On 06/17/2011 09:42 AM, Andreas Pieber wrote:
>>>
>>> Hey,
>>>
>>> On Fri, Jun 17, 2011 at 9:18 AM, Jean-Baptiste Onofré<jb...@nanthrax.net>
>>> wrote:
>>>>
>>>> Following our yesterday concall, I wrote down the minute notes:
>>>>
>>>>
>>>> https://cwiki.apache.org/confluence/display/KARAF/Apache+Karaf+First+Birthday+Meeting+%282011-06-16%29
>>>
>>> This looks great; It gives a very good overview of the topics we've
>>> discussed yesterday.
>>>
>>>> As I said yesterday, I will start to work on the Karaf roadmap page and
>>>> Karaf architecture/implementation draft.
>>>>
>>>> I think that these pages should be easily visible by the website visitor.
>>>> That's why I propose to write it into the Karaf website and not the wiki.
>>>
>>> Well the problem with the homepage is still the contribution. Maybe we
>>> could go somewhere in between and provide only the "headlines" on the
>>> homepage and link to the wiki page?
>>>
>>> Kind regards,
>>> Andreas
>>>
>>> p.s.: thanks for the "birthday party" yesterday! Was cool to get the
>>> names backed up with voices :)
>>
>
>
>
Re: Karaf first birthday concall minute notes
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Ah yeah, I see what you mean.
It's weird, the link is
http://karaf.apache.org/manual/2.1.99-SNAPSHOT/users-guide/installation.html
but the content is "correct" (we can see 2.2.1 version in the content).
I will take a look.
Thanks for the update
Regards
JB
On 06/17/2011 09:49 AM, Achim Nierbeck wrote:
> JB,
>
> +1 for wiki pages as children of the "cap" page :-)
>
> btw. why is the documentation still showing the 2.1.99-SNAPSHOT
> instead of 2.2.1-SNAPSHOT?
>
> regards, Achim
>
> 2011/6/17 Jean-Baptiste Onofré<jb...@nanthrax.net>:
>> Agree Andreas,
>>
>> I think that:
>> - link to the wiki "cap" page in the community area of the website
>> - wiki pages as children of the "cap" page
>>
>> is the most efficient way.
>>
>> Regards
>> JB
>>
>> On 06/17/2011 09:42 AM, Andreas Pieber wrote:
>>>
>>> Hey,
>>>
>>> On Fri, Jun 17, 2011 at 9:18 AM, Jean-Baptiste Onofré<jb...@nanthrax.net>
>>> wrote:
>>>>
>>>> Following our yesterday concall, I wrote down the minute notes:
>>>>
>>>>
>>>> https://cwiki.apache.org/confluence/display/KARAF/Apache+Karaf+First+Birthday+Meeting+%282011-06-16%29
>>>
>>> This looks great; It gives a very good overview of the topics we've
>>> discussed yesterday.
>>>
>>>> As I said yesterday, I will start to work on the Karaf roadmap page and
>>>> Karaf architecture/implementation draft.
>>>>
>>>> I think that these pages should be easily visible by the website visitor.
>>>> That's why I propose to write it into the Karaf website and not the wiki.
>>>
>>> Well the problem with the homepage is still the contribution. Maybe we
>>> could go somewhere in between and provide only the "headlines" on the
>>> homepage and link to the wiki page?
>>>
>>> Kind regards,
>>> Andreas
>>>
>>> p.s.: thanks for the "birthday party" yesterday! Was cool to get the
>>> names backed up with voices :)
>>
>
>
>
Re: Karaf first birthday concall minute notes
Posted by Achim Nierbeck <bc...@googlemail.com>.
JB,
+1 for wiki pages as children of the "cap" page :-)
btw. why is the documentation still showing the 2.1.99-SNAPSHOT
instead of 2.2.1-SNAPSHOT?
regards, Achim
2011/6/17 Jean-Baptiste Onofré <jb...@nanthrax.net>:
> Agree Andreas,
>
> I think that:
> - link to the wiki "cap" page in the community area of the website
> - wiki pages as children of the "cap" page
>
> is the most efficient way.
>
> Regards
> JB
>
> On 06/17/2011 09:42 AM, Andreas Pieber wrote:
>>
>> Hey,
>>
>> On Fri, Jun 17, 2011 at 9:18 AM, Jean-Baptiste Onofré<jb...@nanthrax.net>
>> wrote:
>>>
>>> Following our yesterday concall, I wrote down the minute notes:
>>>
>>>
>>> https://cwiki.apache.org/confluence/display/KARAF/Apache+Karaf+First+Birthday+Meeting+%282011-06-16%29
>>
>> This looks great; It gives a very good overview of the topics we've
>> discussed yesterday.
>>
>>> As I said yesterday, I will start to work on the Karaf roadmap page and
>>> Karaf architecture/implementation draft.
>>>
>>> I think that these pages should be easily visible by the website visitor.
>>> That's why I propose to write it into the Karaf website and not the wiki.
>>
>> Well the problem with the homepage is still the contribution. Maybe we
>> could go somewhere in between and provide only the "headlines" on the
>> homepage and link to the wiki page?
>>
>> Kind regards,
>> Andreas
>>
>> p.s.: thanks for the "birthday party" yesterday! Was cool to get the
>> names backed up with voices :)
>
--
--
*Achim Nierbeck*
Apache Karaf <http://karaf.apache.org/> Committer & PMC
OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/>
Committer & Project Lead
Re: Karaf first birthday concall minute notes
Posted by Andreas Pieber <an...@gmail.com>.
Maybe not the most beautiful solution, but definitely the most
efficient :) --> +1
Kind regards,
Andreas
On Fri, Jun 17, 2011 at 9:46 AM, Jean-Baptiste Onofré <jb...@nanthrax.net> wrote:
> Agree Andreas,
>
> I think that:
> - link to the wiki "cap" page in the community area of the website
> - wiki pages as children of the "cap" page
>
> is the most efficient way.
>
> Regards
> JB
>
> On 06/17/2011 09:42 AM, Andreas Pieber wrote:
>>
>> Hey,
>>
>> On Fri, Jun 17, 2011 at 9:18 AM, Jean-Baptiste Onofré<jb...@nanthrax.net>
>> wrote:
>>>
>>> Following our yesterday concall, I wrote down the minute notes:
>>>
>>>
>>> https://cwiki.apache.org/confluence/display/KARAF/Apache+Karaf+First+Birthday+Meeting+%282011-06-16%29
>>
>> This looks great; It gives a very good overview of the topics we've
>> discussed yesterday.
>>
>>> As I said yesterday, I will start to work on the Karaf roadmap page and
>>> Karaf architecture/implementation draft.
>>>
>>> I think that these pages should be easily visible by the website visitor.
>>> That's why I propose to write it into the Karaf website and not the wiki.
>>
>> Well the problem with the homepage is still the contribution. Maybe we
>> could go somewhere in between and provide only the "headlines" on the
>> homepage and link to the wiki page?
>>
>> Kind regards,
>> Andreas
>>
>> p.s.: thanks for the "birthday party" yesterday! Was cool to get the
>> names backed up with voices :)
>
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Guillaume,
I see the possible advantages of keeping the documentation in
subversion. The problem is that I think they are more academic than real.
Am 17.06.2011 10:59, schrieb Guillaume Nodet:
> There are also lots of benefits of not using cwiki:
> * ability to work offline (that's really a problem with confluence)
The ability to work offline is a real and great benefit of subversion.
> * ability to experiment using branches
I am not sure if this will be used much. On the wiki this can still be
done by creating pages for the changes on branches and later replacing
the original page with it.
That is not a streamlined but works.
I think branches even cause a lot of effort. As most documentation
changes affect several versions you will have to keep the branches in sync.
Another problem is which branch to show in the web. trunk ? Last releaed
versions? All supported branches? I think this will rather confuse people.
> * ability to version documentation easily
As I said in the other mail I think documentation has a different
lifecycle than the code. So I think keeping them together may even be a
bad idea after all. For example if there is an
error in the documentation you most times wil not want to wait for a
patch release to see the fix. You will rather want to see it asap.
Currently we show the manual of version 2.1.99-SNAPSHOT this clearly
shows that we do publish the documentation of the current release.
> * ability to modify several pages at once
May be intersting sometimes for search and replace in all the documentation
> * ability to better track contributions
To really track the contribution before people are committers you need
jiras. Btw a jira is the only way people can submit patches as of now.
So while this sounds good it means that for a fixed typo. You would need
to :
- create a jira issue
- Describe what you want to do
- Checkout the source.
- find the source file that corresponds to the web page
- Make the change
- Test the change with maven
- Create a patch
- submit the patch to jira
- Wait till someone takes the issue
The committer will:
- assing himself to the issue
- update the source
- apply the patch
- test with maven
- commit
Whoever sync the website will:
- update the source
- call a sync script
So I think these are about 16 steps. I think the time from idea to
visible change will be about 10 to 20 days. Three people are involved
typically.
In confluence the contributor does:
- click edit page
- make the change
- save
This takes seconds and only one person is involved.
If the change is bad someone will spot using the subscription and corect
the change.
> On the last one, I actually think giving people modification rights is
> not necessarily a good idea.
> People should be able to become committers but simply contributing
> doc. Do you monitor all the doc changes on cxf / camel made by non
> committers ? And actually, how many modifications are we talking about
> ?
I too think that people should be able to become committers by changing
documentation. Tracking the changes in confluence is no big problem.
Using the subscription changes from someone will be highly visible. So
committers will notice and can vote for the person.
There is even a nice activity view for a contributor:
https://cwiki.apache.org/confluence/display/~christian+schneider
Btw talking about numbers. svnsearch tracks nicely how much was committed:
http://svnsearch.org/svnsearch/repos/ASF/search?from=20110301&path=%2Fkaraf%2Ftrunk%2Fmanual
So it seems we only had 18 commits to the manual since first of march. I
think this is not much.
Sadly I can not see the statistics in the wiki as I do not have the rights.
> Last, we had a vote on that a few months ago, so please go read the
> discussions, as Jean-Baptiste explained, we had some discussions and
> came to a conclusion ... We were using cwiki until a few months.
I will read the discussion there. So perhaps if now is a bad time we
could simply revisit the decision in half a year and review if it was good.
Christian
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Thanks for your feedback Claus.
It confirms that our current solution looks the right one !!
Maybe we can work on the documentation look and feel but it's another topic.
+1 to keep as we are now ;)
Regards
JB
On 06/17/2011 11:09 AM, Claus Ibsen wrote:
> Actually I envy Karaf since you have made the transition from
> confluence to scalate (eg docs in svn).
>
> Maintaining the Camel wiki documentation is becoming a problem with
> the sheer number of releases we have.
> It starts to become a lot of .. if you use Camel version X then bla
> bla, but if you use version Y then bla bla, or if version Z then bla
> bla.
> This is not convenient for end users of Camel to read the
> documentation in this manner.
>
>
> And since Camel 1.x is EOL we still have documentation that only
> applies for that release. Its frankly a big task to go over all the
> wiki pages and remove any obsolete documentation.
>
> And in terms of contributions by people who have edit rights to wiki
> pages and does some changes, then thats a very small number. Maybe
> once a month. Likewise with people who comment on the wiki pages.
>
> Instead having the documentation in svn is a big +1 IMHO. And I would
> love that we did this transition in Camel.
>
> And we had a discussion about this last year. And Hadrian wrote up a
> summary of that
> http://camel.apache.org/site-update-ideas.html
>
>
> On Fri, Jun 17, 2011 at 10:59 AM, Guillaume Nodet<gn...@gmail.com> wrote:
>> There are also lots of benefits of not using cwiki:
>> * ability to work offline (that's really a problem with confluence)
>> * ability to experiment using branches
>> * ability to version documentation easily
>> * ability to modify several pages at once
>> * ability to better track contributions
>>
>> On the last one, I actually think giving people modification rights is
>> not necessarily a good idea.
>> People should be able to become committers but simply contributing
>> doc. Do you monitor all the doc changes on cxf / camel made by non
>> committers ? And actually, how many modifications are we talking about
>> ?
>>
>> Last, we had a vote on that a few months ago, so please go read the
>> discussions, as Jean-Baptiste explained, we had some discussions and
>> came to a conclusion ... We were using cwiki until a few months.
>>
>> On Fri, Jun 17, 2011 at 10:19, Christian Schneider
>> <ch...@die-schneider.net> wrote:
>>> I know that I have proposed this before and then got the answer that this
>>> was discussed already. Still I have the feeling that everybody dislikes the
>>> current way we build our website.... so again a try :-)...
>>>
>>> I would even go a step farther and do as much of the website on the wiki as
>>> possible. Dan Kulp has written an exporter script that syncs the wiki to
>>> static pages so the admins can live with it.
>>>
>>> I think we have to try to make the website and documentation as open as
>>> possible. The wiki allows us to give editing right to anyone with a valid
>>> icla. That is much more accessible than the current site.
>>> Additionally any change can be seen right after the change on the wiki. I
>>> think that is a big motivation. Currently you have to submit a patch for the
>>> website and wait for someone to commit it and then for someeone else to sync
>>> it to the web. This process can take months sometimes. That is quite
>>> frustrating and I am sure it is the reason why we have so few updates to the
>>> site and documentation.
>>> Another nice thing of the wiki is that it is a first step of contribution
>>> below submitting patches. So people can come in contact with the project
>>> gradually.
>>>
>>> Of course the wiki has the problem that it is not synched to the releases
>>> but in cxf and camel this is also not the case. Still it works well there.
>>> The way to couple the documentation to releases is to note for example which
>>> attribute of a command has been introduced in which version. This is niot
>>> perfect but works quite well in practice.
>>>
>>> Christian
>>>
>>>
>>> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>>>>
>>>> Agree Andreas,
>>>>
>>>> I think that:
>>>> - link to the wiki "cap" page in the community area of the website
>>>> - wiki pages as children of the "cap" page
>>>>
>>>> is the most efficient way.
>>>>
>>>> Regards
>>>> JB
>>>
>>> --
>>> Christian Schneider
>>> http://www.liquid-reality.de
>>>
>>> Open Source Architect
>>> http://www.talend.com
>>>
>>>
>>
>>
>>
>> --
>> ------------------------
>> Guillaume Nodet
>> ------------------------
>> Blog: http://gnodet.blogspot.com/
>> ------------------------
>> Open Source SOA
>> http://fusesource.com
>>
>
>
>
Re: Karaf first birthday concall minute notes
Posted by James Strachan <ja...@fusesource.com>.
On 17 June 2011 11:46, Guillaume Nodet <gn...@gmail.com> wrote:
> On Fri, Jun 17, 2011 at 12:03, Christian Schneider
> <ch...@die-schneider.net> wrote:
>> Hi Claus,
>>
>> great that you weigh in with your experience from camel. You do a lot of
>> documentation changes so I trust you know how the wiki feels in practice.
>> You should also try the process in suversion though. I think it looks much
>> more appealing until you do it.
>>
>> The different version are a big problem of course. But the downside of
>> subversion in this case would be that you would either have to port every
>> change that applies to all versions back to each version or you would loose
>> these changes in the older documentations.
>
> You should try git really. It helps a lot on those problems.
FWIW I used to really detest branches & tried to avoid them at all
costs. Thanks to git I now really like branches & find myself using
them more and more :)
--
James
-------
FuseSource
Email: james@fusesource.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration and Messaging
Re: Karaf first birthday concall minute notes
Posted by Guillaume Nodet <gn...@gmail.com>.
On Fri, Jun 17, 2011 at 12:03, Christian Schneider
<ch...@die-schneider.net> wrote:
> Hi Claus,
>
> great that you weigh in with your experience from camel. You do a lot of
> documentation changes so I trust you know how the wiki feels in practice.
> You should also try the process in suversion though. I think it looks much
> more appealing until you do it.
>
> The different version are a big problem of course. But the downside of
> subversion in this case would be that you would either have to port every
> change that applies to all versions back to each version or you would loose
> these changes in the older documentations.
You should try git really. It helps a lot on those problems.
>
> I think the solution for camel in the wiki is to clearly define which
> versions we support and remove the depreacted documentation. Of course we
> can keep a pdf of the old documentation for people who use older versions.
>
> Still your points sure have value and I think they show that it would not
> make sense to revert to wiki right now. But I think it makes sense to
> revisit the decision after some time to see if the advantages of subversion
> based docu really outweigh the problems.
>
> Christian
>
> Am 17.06.2011 11:09, schrieb Claus Ibsen:
>>
>> Actually I envy Karaf since you have made the transition from
>> confluence to scalate (eg docs in svn).
>>
>> Maintaining the Camel wiki documentation is becoming a problem with
>> the sheer number of releases we have.
>> It starts to become a lot of .. if you use Camel version X then bla
>> bla, but if you use version Y then bla bla, or if version Z then bla
>> bla.
>> This is not convenient for end users of Camel to read the
>> documentation in this manner.
>>
>>
>> And since Camel 1.x is EOL we still have documentation that only
>> applies for that release. Its frankly a big task to go over all the
>> wiki pages and remove any obsolete documentation.
>>
>> And in terms of contributions by people who have edit rights to wiki
>> pages and does some changes, then thats a very small number. Maybe
>> once a month. Likewise with people who comment on the wiki pages.
>>
>> Instead having the documentation in svn is a big +1 IMHO. And I would
>> love that we did this transition in Camel.
>>
>> And we had a discussion about this last year. And Hadrian wrote up a
>> summary of that
>> http://camel.apache.org/site-update-ideas.html
>
> --
> --
> Christian Schneider
> http://www.liquid-reality.de
>
> Open Source Architect
> Talend Application Integration Division http://www.talend.com
>
>
--
------------------------
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com
Re: Karaf first birthday concall minute notes
Posted by Ioannis Canellos <io...@gmail.com>.
Hi,
I like both approaches the same. I consider the benefits of one over the
other minor.
What its really important to me is the content. I find Camel documentation
sexy not because of the (wiki, svn etc), but because of the hard work the
riders put in it.
So, I would propose to stop arguing on what its best and start documenting
like there is no tomorrow ;-)
--
*Ioannis Canellos*
*
http://iocanel.blogspot.com
Apache Karaf <http://karaf.apache.org/> Committer & PMC
Apache ServiceMix <http://servicemix.apache.org/> Committer
*
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Claus,
great that you weigh in with your experience from camel. You do a lot of
documentation changes so I trust you know how the wiki feels in practice.
You should also try the process in suversion though. I think it looks
much more appealing until you do it.
The different version are a big problem of course. But the downside of
subversion in this case would be that you would either have to port
every change that applies to all versions back to each version or you
would loose these changes in the older documentations.
I think the solution for camel in the wiki is to clearly define which
versions we support and remove the depreacted documentation. Of course
we can keep a pdf of the old documentation for people who use older
versions.
Still your points sure have value and I think they show that it would
not make sense to revert to wiki right now. But I think it makes sense
to revisit the decision after some time to see if the advantages of
subversion based docu really outweigh the problems.
Christian
Am 17.06.2011 11:09, schrieb Claus Ibsen:
> Actually I envy Karaf since you have made the transition from
> confluence to scalate (eg docs in svn).
>
> Maintaining the Camel wiki documentation is becoming a problem with
> the sheer number of releases we have.
> It starts to become a lot of .. if you use Camel version X then bla
> bla, but if you use version Y then bla bla, or if version Z then bla
> bla.
> This is not convenient for end users of Camel to read the
> documentation in this manner.
>
>
> And since Camel 1.x is EOL we still have documentation that only
> applies for that release. Its frankly a big task to go over all the
> wiki pages and remove any obsolete documentation.
>
> And in terms of contributions by people who have edit rights to wiki
> pages and does some changes, then thats a very small number. Maybe
> once a month. Likewise with people who comment on the wiki pages.
>
> Instead having the documentation in svn is a big +1 IMHO. And I would
> love that we did this transition in Camel.
>
> And we had a discussion about this last year. And Hadrian wrote up a
> summary of that
> http://camel.apache.org/site-update-ideas.html
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by Claus Ibsen <cl...@gmail.com>.
Actually I envy Karaf since you have made the transition from
confluence to scalate (eg docs in svn).
Maintaining the Camel wiki documentation is becoming a problem with
the sheer number of releases we have.
It starts to become a lot of .. if you use Camel version X then bla
bla, but if you use version Y then bla bla, or if version Z then bla
bla.
This is not convenient for end users of Camel to read the
documentation in this manner.
And since Camel 1.x is EOL we still have documentation that only
applies for that release. Its frankly a big task to go over all the
wiki pages and remove any obsolete documentation.
And in terms of contributions by people who have edit rights to wiki
pages and does some changes, then thats a very small number. Maybe
once a month. Likewise with people who comment on the wiki pages.
Instead having the documentation in svn is a big +1 IMHO. And I would
love that we did this transition in Camel.
And we had a discussion about this last year. And Hadrian wrote up a
summary of that
http://camel.apache.org/site-update-ideas.html
On Fri, Jun 17, 2011 at 10:59 AM, Guillaume Nodet <gn...@gmail.com> wrote:
> There are also lots of benefits of not using cwiki:
> * ability to work offline (that's really a problem with confluence)
> * ability to experiment using branches
> * ability to version documentation easily
> * ability to modify several pages at once
> * ability to better track contributions
>
> On the last one, I actually think giving people modification rights is
> not necessarily a good idea.
> People should be able to become committers but simply contributing
> doc. Do you monitor all the doc changes on cxf / camel made by non
> committers ? And actually, how many modifications are we talking about
> ?
>
> Last, we had a vote on that a few months ago, so please go read the
> discussions, as Jean-Baptiste explained, we had some discussions and
> came to a conclusion ... We were using cwiki until a few months.
>
> On Fri, Jun 17, 2011 at 10:19, Christian Schneider
> <ch...@die-schneider.net> wrote:
>> I know that I have proposed this before and then got the answer that this
>> was discussed already. Still I have the feeling that everybody dislikes the
>> current way we build our website.... so again a try :-)...
>>
>> I would even go a step farther and do as much of the website on the wiki as
>> possible. Dan Kulp has written an exporter script that syncs the wiki to
>> static pages so the admins can live with it.
>>
>> I think we have to try to make the website and documentation as open as
>> possible. The wiki allows us to give editing right to anyone with a valid
>> icla. That is much more accessible than the current site.
>> Additionally any change can be seen right after the change on the wiki. I
>> think that is a big motivation. Currently you have to submit a patch for the
>> website and wait for someone to commit it and then for someeone else to sync
>> it to the web. This process can take months sometimes. That is quite
>> frustrating and I am sure it is the reason why we have so few updates to the
>> site and documentation.
>> Another nice thing of the wiki is that it is a first step of contribution
>> below submitting patches. So people can come in contact with the project
>> gradually.
>>
>> Of course the wiki has the problem that it is not synched to the releases
>> but in cxf and camel this is also not the case. Still it works well there.
>> The way to couple the documentation to releases is to note for example which
>> attribute of a command has been introduced in which version. This is niot
>> perfect but works quite well in practice.
>>
>> Christian
>>
>>
>> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>>>
>>> Agree Andreas,
>>>
>>> I think that:
>>> - link to the wiki "cap" page in the community area of the website
>>> - wiki pages as children of the "cap" page
>>>
>>> is the most efficient way.
>>>
>>> Regards
>>> JB
>>
>> --
>> Christian Schneider
>> http://www.liquid-reality.de
>>
>> Open Source Architect
>> http://www.talend.com
>>
>>
>
>
>
> --
> ------------------------
> Guillaume Nodet
> ------------------------
> Blog: http://gnodet.blogspot.com/
> ------------------------
> Open Source SOA
> http://fusesource.com
>
--
Claus Ibsen
-----------------
FuseSource
Email: cibsen@fusesource.com
Web: http://fusesource.com
Twitter: davsclaus, fusenews
Blog: http://davsclaus.blogspot.com/
Author of Camel in Action: http://www.manning.com/ibsen/
Re: Karaf first birthday concall minute notes
Posted by Achim Nierbeck <bc...@googlemail.com>.
JB, Guillaume,
this is all very true and I think it is the best solution for it right now.
I only think that we need to improve on the documentation.
1) Add the current trunk-documentation
--> the nightly build should somehow generate it and add it to the
page or something the like :-)
2) Some special pages, like contributor and the roadmap need a better
"place" in the page.
Thanks, Achim
2011/6/17 Jean-Baptiste Onofré <jb...@nanthrax.net>:
> Thanks Guillaume,
>
> you mentioned some points I forgot ;)
>
> Regards
> JB
>
> On 06/17/2011 10:59 AM, Guillaume Nodet wrote:
>>
>> There are also lots of benefits of not using cwiki:
>> * ability to work offline (that's really a problem with confluence)
>> * ability to experiment using branches
>> * ability to version documentation easily
>> * ability to modify several pages at once
>> * ability to better track contributions
>>
>> On the last one, I actually think giving people modification rights is
>> not necessarily a good idea.
>> People should be able to become committers but simply contributing
>> doc. Do you monitor all the doc changes on cxf / camel made by non
>> committers ? And actually, how many modifications are we talking about
>> ?
>>
>> Last, we had a vote on that a few months ago, so please go read the
>> discussions, as Jean-Baptiste explained, we had some discussions and
>> came to a conclusion ... We were using cwiki until a few months.
>>
>> On Fri, Jun 17, 2011 at 10:19, Christian Schneider
>> <ch...@die-schneider.net> wrote:
>>>
>>> I know that I have proposed this before and then got the answer that this
>>> was discussed already. Still I have the feeling that everybody dislikes
>>> the
>>> current way we build our website.... so again a try :-)...
>>>
>>> I would even go a step farther and do as much of the website on the wiki
>>> as
>>> possible. Dan Kulp has written an exporter script that syncs the wiki to
>>> static pages so the admins can live with it.
>>>
>>> I think we have to try to make the website and documentation as open as
>>> possible. The wiki allows us to give editing right to anyone with a valid
>>> icla. That is much more accessible than the current site.
>>> Additionally any change can be seen right after the change on the wiki. I
>>> think that is a big motivation. Currently you have to submit a patch for
>>> the
>>> website and wait for someone to commit it and then for someeone else to
>>> sync
>>> it to the web. This process can take months sometimes. That is quite
>>> frustrating and I am sure it is the reason why we have so few updates to
>>> the
>>> site and documentation.
>>> Another nice thing of the wiki is that it is a first step of contribution
>>> below submitting patches. So people can come in contact with the project
>>> gradually.
>>>
>>> Of course the wiki has the problem that it is not synched to the releases
>>> but in cxf and camel this is also not the case. Still it works well
>>> there.
>>> The way to couple the documentation to releases is to note for example
>>> which
>>> attribute of a command has been introduced in which version. This is niot
>>> perfect but works quite well in practice.
>>>
>>> Christian
>>>
>>>
>>> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>>>>
>>>> Agree Andreas,
>>>>
>>>> I think that:
>>>> - link to the wiki "cap" page in the community area of the website
>>>> - wiki pages as children of the "cap" page
>>>>
>>>> is the most efficient way.
>>>>
>>>> Regards
>>>> JB
>>>
>>> --
>>> Christian Schneider
>>> http://www.liquid-reality.de
>>>
>>> Open Source Architect
>>> http://www.talend.com
>>>
>>>
>>
>>
>>
>
--
--
*Achim Nierbeck*
Apache Karaf <http://karaf.apache.org/> Committer & PMC
OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/>
Committer & Project Lead
Re: Karaf first birthday concall minute notes
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Thanks Guillaume,
you mentioned some points I forgot ;)
Regards
JB
On 06/17/2011 10:59 AM, Guillaume Nodet wrote:
> There are also lots of benefits of not using cwiki:
> * ability to work offline (that's really a problem with confluence)
> * ability to experiment using branches
> * ability to version documentation easily
> * ability to modify several pages at once
> * ability to better track contributions
>
> On the last one, I actually think giving people modification rights is
> not necessarily a good idea.
> People should be able to become committers but simply contributing
> doc. Do you monitor all the doc changes on cxf / camel made by non
> committers ? And actually, how many modifications are we talking about
> ?
>
> Last, we had a vote on that a few months ago, so please go read the
> discussions, as Jean-Baptiste explained, we had some discussions and
> came to a conclusion ... We were using cwiki until a few months.
>
> On Fri, Jun 17, 2011 at 10:19, Christian Schneider
> <ch...@die-schneider.net> wrote:
>> I know that I have proposed this before and then got the answer that this
>> was discussed already. Still I have the feeling that everybody dislikes the
>> current way we build our website.... so again a try :-)...
>>
>> I would even go a step farther and do as much of the website on the wiki as
>> possible. Dan Kulp has written an exporter script that syncs the wiki to
>> static pages so the admins can live with it.
>>
>> I think we have to try to make the website and documentation as open as
>> possible. The wiki allows us to give editing right to anyone with a valid
>> icla. That is much more accessible than the current site.
>> Additionally any change can be seen right after the change on the wiki. I
>> think that is a big motivation. Currently you have to submit a patch for the
>> website and wait for someone to commit it and then for someeone else to sync
>> it to the web. This process can take months sometimes. That is quite
>> frustrating and I am sure it is the reason why we have so few updates to the
>> site and documentation.
>> Another nice thing of the wiki is that it is a first step of contribution
>> below submitting patches. So people can come in contact with the project
>> gradually.
>>
>> Of course the wiki has the problem that it is not synched to the releases
>> but in cxf and camel this is also not the case. Still it works well there.
>> The way to couple the documentation to releases is to note for example which
>> attribute of a command has been introduced in which version. This is niot
>> perfect but works quite well in practice.
>>
>> Christian
>>
>>
>> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>>>
>>> Agree Andreas,
>>>
>>> I think that:
>>> - link to the wiki "cap" page in the community area of the website
>>> - wiki pages as children of the "cap" page
>>>
>>> is the most efficient way.
>>>
>>> Regards
>>> JB
>>
>> --
>> Christian Schneider
>> http://www.liquid-reality.de
>>
>> Open Source Architect
>> http://www.talend.com
>>
>>
>
>
>
Re: Karaf first birthday concall minute notes
Posted by Guillaume Nodet <gn...@gmail.com>.
There are also lots of benefits of not using cwiki:
* ability to work offline (that's really a problem with confluence)
* ability to experiment using branches
* ability to version documentation easily
* ability to modify several pages at once
* ability to better track contributions
On the last one, I actually think giving people modification rights is
not necessarily a good idea.
People should be able to become committers but simply contributing
doc. Do you monitor all the doc changes on cxf / camel made by non
committers ? And actually, how many modifications are we talking about
?
Last, we had a vote on that a few months ago, so please go read the
discussions, as Jean-Baptiste explained, we had some discussions and
came to a conclusion ... We were using cwiki until a few months.
On Fri, Jun 17, 2011 at 10:19, Christian Schneider
<ch...@die-schneider.net> wrote:
> I know that I have proposed this before and then got the answer that this
> was discussed already. Still I have the feeling that everybody dislikes the
> current way we build our website.... so again a try :-)...
>
> I would even go a step farther and do as much of the website on the wiki as
> possible. Dan Kulp has written an exporter script that syncs the wiki to
> static pages so the admins can live with it.
>
> I think we have to try to make the website and documentation as open as
> possible. The wiki allows us to give editing right to anyone with a valid
> icla. That is much more accessible than the current site.
> Additionally any change can be seen right after the change on the wiki. I
> think that is a big motivation. Currently you have to submit a patch for the
> website and wait for someone to commit it and then for someeone else to sync
> it to the web. This process can take months sometimes. That is quite
> frustrating and I am sure it is the reason why we have so few updates to the
> site and documentation.
> Another nice thing of the wiki is that it is a first step of contribution
> below submitting patches. So people can come in contact with the project
> gradually.
>
> Of course the wiki has the problem that it is not synched to the releases
> but in cxf and camel this is also not the case. Still it works well there.
> The way to couple the documentation to releases is to note for example which
> attribute of a command has been introduced in which version. This is niot
> perfect but works quite well in practice.
>
> Christian
>
>
> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>>
>> Agree Andreas,
>>
>> I think that:
>> - link to the wiki "cap" page in the community area of the website
>> - wiki pages as children of the "cap" page
>>
>> is the most efficient way.
>>
>> Regards
>> JB
>
> --
> Christian Schneider
> http://www.liquid-reality.de
>
> Open Source Architect
> http://www.talend.com
>
>
--
------------------------
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com
Re: Karaf first birthday concall minute notes
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Hi Christian,
I have no problem to discuss about that and submit to a vote.
First, a quick history about that :)
On both Karaf and ServiceMix, we had (and still have) documentation
requirements with a multi-format outputs (PDF, HTML) and professional
look'n feel.
Another requirement is to be able to "link" the documentation with a
specific Karaf version. The documentation could be widely different
between Karaf 2.1.x and Karaf 3.0.x for instance.
Starting with these requirements, we discussed around:
1/ usage of the Apache confluence wiki to store the documentation and
use of an "external" tool (such as Prince) to extract content from the
wiki and generate the document output (PDF). It looks like the way it
does in Camel.
2/ usage of DocBook directly into the Karaf svn repo
3/ usage of Scalate directly into the Karaf svn repo
Here's the conclusions that we had regarding the previous points:
1/ it seems that the Apache confluence wiki future is not really clear.
There were discussion around Apache CMS, cwiki EOL, etc.
If we "invest" a lot in the documentation on the wiki, it could "cost" a
lot very soon depending of the cwiki future. That's why we voted to not
use directly cwiki.
2/ DocBook is XML document, very rich namespace but no always easy (I
don't say that as I love DocBook but it's the feedback that we got ;)).
3/ Scalate documentation was the choice because the syntax is really
close to wiki and the mechanism is like DocBook document generation. So
it's like a solution in the middle.
To be honest, I was more on 2/ or 3/ at the beginning. But, when I see
the Camel documentation and website, I'm quite around to revert my point
of view ;). It's clear that Karaf (and ServiceMix, that's why I added
ServiceMix dev mailing list in copy of this e-mail) documentation and
website could be managed in the same way that Camel does.
My only concern is that we decide to move back to cwiki (I don't mind to
make the effort, I will do it), we need to have a clear view about the
cwiki future and relationship with Apache CMS.
I'm sure that the ASF members could provide us more information:
@gnodet, @dkulp ?
Regards
JB
On 06/17/2011 10:19 AM, Christian Schneider wrote:
> I know that I have proposed this before and then got the answer that
> this was discussed already. Still I have the feeling that everybody
> dislikes the current way we build our website.... so again a try :-)...
>
> I would even go a step farther and do as much of the website on the wiki
> as possible. Dan Kulp has written an exporter script that syncs the wiki
> to static pages so the admins can live with it.
>
> I think we have to try to make the website and documentation as open as
> possible. The wiki allows us to give editing right to anyone with a
> valid icla. That is much more accessible than the current site.
> Additionally any change can be seen right after the change on the wiki.
> I think that is a big motivation. Currently you have to submit a patch
> for the website and wait for someone to commit it and then for someeone
> else to sync it to the web. This process can take months sometimes. That
> is quite frustrating and I am sure it is the reason why we have so few
> updates to the site and documentation.
> Another nice thing of the wiki is that it is a first step of
> contribution below submitting patches. So people can come in contact
> with the project gradually.
>
> Of course the wiki has the problem that it is not synched to the
> releases but in cxf and camel this is also not the case. Still it works
> well there. The way to couple the documentation to releases is to note
> for example which attribute of a command has been introduced in which
> version. This is niot perfect but works quite well in practice.
>
> Christian
>
>
> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>> Agree Andreas,
>>
>> I think that:
>> - link to the wiki "cap" page in the community area of the website
>> - wiki pages as children of the "cap" page
>>
>> is the most efficient way.
>>
>> Regards
>> JB
>
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
Perhaps the account where jenkins runs has a ssh key. Then we could
allow this key on the server. I think infra could do such a thing in
their settings.xml.
Christian
Am 17.06.2011 15:23, schrieb Guillaume Nodet:
> On Fri, Jun 17, 2011 at 14:39, Jamie G.<ja...@gmail.com> wrote:
>> Good morning all,
>>
>> It was really nice getting to put voices to the names here on IRC
>> yesterday. I think having these community conference calls are a great
>> way to bring our global team together :)
>>
>> Jean-Baptiste, the meeting notes look good. I really like the idea of
>> having these calls regularly every 2 or 3 months.
>>
>> As to scalate...
>>
>> As a mechanism to produce the manuals I'm fine with its usage.
>>
>> As a mechanism to produce our website I've had several issues, and
>> quite frankly just do my best to get past them with copious amounts of
>> help over IRC from community members. To be honest, updating a wiki or
>> scalate site requires the contributor to learn some amount of a
>> framework - wikis being common lowers the bar in general while scalate
>> requires something of an investment of time (not that its huge). I
>> think what slows or stops a new user from jumping into altering the
>> website (contributing a patch) is that hitting scalate for the first
>> time it may appear to be more daunting than it is... it definitely is
>> more work to do, requiring more touch time to get things all together
>> (just my experience). Perhaps the solution is to create a tutorial on
>> how to update the site, that explicitly shows a user where to get the
>> code, how to build/test it, and where to create the JIRA& attach
>> their patch. Another tutorial should also be made to explain how the
>> karaf site it put together; I know that during each release I spend
>> far too much time trying to find all the places I need to update or
>> append to in the source, vs the old just add page where I want it on
>> the wiki site (perhaps there is a better way I am unfamiliar with, if
>> there is please let me know).
> Yeah, you're right. We should have a web page that can be used as a
> tutorial for updating the web site.
>
>> Setting up a nightly CI build to deploy the website nightly would help
>> keep the site more up to date with recent commits. I have to agree
>> with Christian that updates to the website have been slow getting into
>> production. I know from my experience setting up to update our webpage
>> took a bit of messing around, so not having to do that would be a
>> boost to productivity. This being said do we have a username/password
>> combo that we can leave on the CI box? The current setup requires
>> committer credentials to upload/deploy the site, perhaps infra has an
>> account such as this already created though - we should find out from
>> them if something like that is available.
> Good point. As a work around, a small cron job would do the trick,
> but CI would be way better if possible.
>
>> Cheers,
>> Jamie
>>
>> On Fri, Jun 17, 2011 at 9:12 AM, Guillaume Nodet<gn...@gmail.com> wrote:
>>> The setup is slightly different as we have two web sites, one for the
>>> manuals which is versioned and one for the main web site which isn't.
>>> Things such as committers list, board reports and such aren't really
>>> tied to a release schedule imho.
>>>
>>> On Fri, Jun 17, 2011 at 13:38, James Strachan<ja...@fusesource.com> wrote:
>>>> BTW we found on the Scalate project we wanted 2 continuous website
>>>> builds; the current production site branch (i.e. docs for the last
>>>> major release); so the thing to make http://karaf.apache.org/. Then a
>>>> continuous build of the new version (trunk);
>>>> http://karaf.apache.org/versions/3.0-SNAPSHOT (or whatever).
>>>>
>>>> Then folks can update the current production website in one branch; or
>>>> update what will be the next major release (which may be months away);
>>>> but folks can still view/read the docs for trunk on the website if
>>>> they want.
>>>>
>>>> Also when a release is made, the docs are deployed to a fixed area:
>>>> http://karaf.apache.org/versions/2.2.3/ or whatever. Then you've just
>>>> gotta maintain the http://karaf.apache.org/versions/index.html page to
>>>> link to the various available versions etc.
>>>>
>>>>
>>>> On 17 June 2011 12:28, James Strachan<ja...@fusesource.com> wrote:
>>>>> On 17 June 2011 12:16, Christian Schneider<ch...@die-schneider.net> wrote:
>>>>>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>>>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>>>>>> the doc without being or becoming committers.
>>>>>>> I don't want to change a technical decision based on the fact that
>>>>>>> people *might* need something, but rather what people actually need.
>>>>>>> You are a committer, so you can access / modify the documentation
>>>>>>> without any problems. So what are your real problems with the current
>>>>>>> solution ? We can easily set up nightly uploads or even an hourly
>>>>>>> cron job (though given the change rate, i think a nightly one should
>>>>>>> be sufficient). If you need an editor, you always find some software
>>>>>>> I think such as
>>>>>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>>>>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>>>>>> your changes immediately.
>>>>>> For me as a committer now it is ok. I also do not have problems with editing
>>>>>> wiki syntax text files by hand. After reading all the comments I think that
>>>>>> the solution is good for now. I just fear that we might not really attract
>>>>>> people to help. But you are right people who just work on the documentation
>>>>>> are rare anyway.
>>>>>>
>>>>>> It would be great if we could establish an automatic update of the website
>>>>>> for trunk and the current production branch. Ideal would be a script like in
>>>>>> jenkins that only fires when there are real changes then it can be run in
>>>>>> very short cycles.
>>>>> Its really no different from a regular continuous integration build
>>>>> really; building& deploying the website is just a different mvn
>>>>> plugin so its like doing snapshot deploy builds.
>>>>>
>>>>>
>>>>>> Btw. How about using jenkins to update the website? The
>>>>>> update just has to be callable from maven and we have to authenticate in
>>>>>> some way. Jenkins would also allow to track when and why updates have beem
>>>>>> done.
>>>>> We've been doing this on the Scalate project for a while btw; its just
>>>>> a matter of setting up a jenkins build in the right branch and using a
>>>>> profile in the maven build to do the deploy of the website project (as
>>>>> you probably don't want other builds deploying the website by
>>>>> default).
>>>>>
>>>>> This kinda thing does the trick in the website pom...
>>>>>
>>>>> <plugin>
>>>>> <groupId>org.fusesource.scalate</groupId>
>>>>> <artifactId>maven-scalate-plugin</artifactId>
>>>>> <version>${project.version}</version>
>>>>> <configuration>
>>>>>
>>>>> <remoteServerId>people.apache.org</remoteServerId>
>>>>>
>>>>> <!-- server stuff here - scp or dav or whatnot... -->
>>>>> <!-- TODO fixme - i just made this up .... --->
>>>>> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
>>>>> </configuration>
>>>>> <executions>
>>>>> <execution>
>>>>> <id>sitegen</id>
>>>>> <goals>
>>>>> <goal>sitegen</goal>
>>>>> </goals>
>>>>> <phase>package</phase>
>>>>> </execution>
>>>>> <execution>
>>>>> <id>deploy</id>
>>>>> <goals>
>>>>> <goal>deploy</goal>
>>>>> </goals>
>>>>> <phase>deploy</phase>
>>>>> </execution>
>>>>> </executions>
>>>>> </plugin>
>>>>>
>>>>> --
>>>>> James
>>>>> -------
>>>>> FuseSource
>>>>> Email: james@fusesource.com
>>>>> Web: http://fusesource.com
>>>>> Twitter: jstrachan, fusenews
>>>>> Blog: http://macstrac.blogspot.com/
>>>>>
>>>>> Open Source Integration and Messaging
>>>>>
>>>>
>>>>
>>>> --
>>>> James
>>>> -------
>>>> FuseSource
>>>> Email: james@fusesource.com
>>>> Web: http://fusesource.com
>>>> Twitter: jstrachan, fusenews
>>>> Blog: http://macstrac.blogspot.com/
>>>>
>>>> Open Source Integration and Messaging
>>>>
>>>
>>>
>>> --
>>> ------------------------
>>> Guillaume Nodet
>>> ------------------------
>>> Blog: http://gnodet.blogspot.com/
>>> ------------------------
>>> Open Source SOA
>>> http://fusesource.com
>>>
>
>
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by Guillaume Nodet <gn...@gmail.com>.
On Fri, Jun 17, 2011 at 14:39, Jamie G. <ja...@gmail.com> wrote:
> Good morning all,
>
> It was really nice getting to put voices to the names here on IRC
> yesterday. I think having these community conference calls are a great
> way to bring our global team together :)
>
> Jean-Baptiste, the meeting notes look good. I really like the idea of
> having these calls regularly every 2 or 3 months.
>
> As to scalate...
>
> As a mechanism to produce the manuals I'm fine with its usage.
>
> As a mechanism to produce our website I've had several issues, and
> quite frankly just do my best to get past them with copious amounts of
> help over IRC from community members. To be honest, updating a wiki or
> scalate site requires the contributor to learn some amount of a
> framework - wikis being common lowers the bar in general while scalate
> requires something of an investment of time (not that its huge). I
> think what slows or stops a new user from jumping into altering the
> website (contributing a patch) is that hitting scalate for the first
> time it may appear to be more daunting than it is... it definitely is
> more work to do, requiring more touch time to get things all together
> (just my experience). Perhaps the solution is to create a tutorial on
> how to update the site, that explicitly shows a user where to get the
> code, how to build/test it, and where to create the JIRA & attach
> their patch. Another tutorial should also be made to explain how the
> karaf site it put together; I know that during each release I spend
> far too much time trying to find all the places I need to update or
> append to in the source, vs the old just add page where I want it on
> the wiki site (perhaps there is a better way I am unfamiliar with, if
> there is please let me know).
Yeah, you're right. We should have a web page that can be used as a
tutorial for updating the web site.
>
> Setting up a nightly CI build to deploy the website nightly would help
> keep the site more up to date with recent commits. I have to agree
> with Christian that updates to the website have been slow getting into
> production. I know from my experience setting up to update our webpage
> took a bit of messing around, so not having to do that would be a
> boost to productivity. This being said do we have a username/password
> combo that we can leave on the CI box? The current setup requires
> committer credentials to upload/deploy the site, perhaps infra has an
> account such as this already created though - we should find out from
> them if something like that is available.
Good point. As a work around, a small cron job would do the trick,
but CI would be way better if possible.
>
> Cheers,
> Jamie
>
> On Fri, Jun 17, 2011 at 9:12 AM, Guillaume Nodet <gn...@gmail.com> wrote:
>> The setup is slightly different as we have two web sites, one for the
>> manuals which is versioned and one for the main web site which isn't.
>> Things such as committers list, board reports and such aren't really
>> tied to a release schedule imho.
>>
>> On Fri, Jun 17, 2011 at 13:38, James Strachan <ja...@fusesource.com> wrote:
>>> BTW we found on the Scalate project we wanted 2 continuous website
>>> builds; the current production site branch (i.e. docs for the last
>>> major release); so the thing to make http://karaf.apache.org/. Then a
>>> continuous build of the new version (trunk);
>>> http://karaf.apache.org/versions/3.0-SNAPSHOT (or whatever).
>>>
>>> Then folks can update the current production website in one branch; or
>>> update what will be the next major release (which may be months away);
>>> but folks can still view/read the docs for trunk on the website if
>>> they want.
>>>
>>> Also when a release is made, the docs are deployed to a fixed area:
>>> http://karaf.apache.org/versions/2.2.3/ or whatever. Then you've just
>>> gotta maintain the http://karaf.apache.org/versions/index.html page to
>>> link to the various available versions etc.
>>>
>>>
>>> On 17 June 2011 12:28, James Strachan <ja...@fusesource.com> wrote:
>>>> On 17 June 2011 12:16, Christian Schneider <ch...@die-schneider.net> wrote:
>>>>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>>>>
>>>>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>>>>> the doc without being or becoming committers.
>>>>>> I don't want to change a technical decision based on the fact that
>>>>>> people *might* need something, but rather what people actually need.
>>>>>> You are a committer, so you can access / modify the documentation
>>>>>> without any problems. So what are your real problems with the current
>>>>>> solution ? We can easily set up nightly uploads or even an hourly
>>>>>> cron job (though given the change rate, i think a nightly one should
>>>>>> be sufficient). If you need an editor, you always find some software
>>>>>> I think such as
>>>>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>>>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>>>>> your changes immediately.
>>>>>
>>>>> For me as a committer now it is ok. I also do not have problems with editing
>>>>> wiki syntax text files by hand. After reading all the comments I think that
>>>>> the solution is good for now. I just fear that we might not really attract
>>>>> people to help. But you are right people who just work on the documentation
>>>>> are rare anyway.
>>>>>
>>>>> It would be great if we could establish an automatic update of the website
>>>>> for trunk and the current production branch. Ideal would be a script like in
>>>>> jenkins that only fires when there are real changes then it can be run in
>>>>> very short cycles.
>>>>
>>>> Its really no different from a regular continuous integration build
>>>> really; building & deploying the website is just a different mvn
>>>> plugin so its like doing snapshot deploy builds.
>>>>
>>>>
>>>>> Btw. How about using jenkins to update the website? The
>>>>> update just has to be callable from maven and we have to authenticate in
>>>>> some way. Jenkins would also allow to track when and why updates have beem
>>>>> done.
>>>>
>>>> We've been doing this on the Scalate project for a while btw; its just
>>>> a matter of setting up a jenkins build in the right branch and using a
>>>> profile in the maven build to do the deploy of the website project (as
>>>> you probably don't want other builds deploying the website by
>>>> default).
>>>>
>>>> This kinda thing does the trick in the website pom...
>>>>
>>>> <plugin>
>>>> <groupId>org.fusesource.scalate</groupId>
>>>> <artifactId>maven-scalate-plugin</artifactId>
>>>> <version>${project.version}</version>
>>>> <configuration>
>>>>
>>>> <remoteServerId>people.apache.org</remoteServerId>
>>>>
>>>> <!-- server stuff here - scp or dav or whatnot... -->
>>>> <!-- TODO fixme - i just made this up .... --->
>>>> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
>>>> </configuration>
>>>> <executions>
>>>> <execution>
>>>> <id>sitegen</id>
>>>> <goals>
>>>> <goal>sitegen</goal>
>>>> </goals>
>>>> <phase>package</phase>
>>>> </execution>
>>>> <execution>
>>>> <id>deploy</id>
>>>> <goals>
>>>> <goal>deploy</goal>
>>>> </goals>
>>>> <phase>deploy</phase>
>>>> </execution>
>>>> </executions>
>>>> </plugin>
>>>>
>>>> --
>>>> James
>>>> -------
>>>> FuseSource
>>>> Email: james@fusesource.com
>>>> Web: http://fusesource.com
>>>> Twitter: jstrachan, fusenews
>>>> Blog: http://macstrac.blogspot.com/
>>>>
>>>> Open Source Integration and Messaging
>>>>
>>>
>>>
>>>
>>> --
>>> James
>>> -------
>>> FuseSource
>>> Email: james@fusesource.com
>>> Web: http://fusesource.com
>>> Twitter: jstrachan, fusenews
>>> Blog: http://macstrac.blogspot.com/
>>>
>>> Open Source Integration and Messaging
>>>
>>
>>
>>
>> --
>> ------------------------
>> Guillaume Nodet
>> ------------------------
>> Blog: http://gnodet.blogspot.com/
>> ------------------------
>> Open Source SOA
>> http://fusesource.com
>>
>
--
------------------------
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com
Re: Karaf first birthday concall minute notes
Posted by "Jamie G." <ja...@gmail.com>.
Good morning all,
It was really nice getting to put voices to the names here on IRC
yesterday. I think having these community conference calls are a great
way to bring our global team together :)
Jean-Baptiste, the meeting notes look good. I really like the idea of
having these calls regularly every 2 or 3 months.
As to scalate...
As a mechanism to produce the manuals I'm fine with its usage.
As a mechanism to produce our website I've had several issues, and
quite frankly just do my best to get past them with copious amounts of
help over IRC from community members. To be honest, updating a wiki or
scalate site requires the contributor to learn some amount of a
framework - wikis being common lowers the bar in general while scalate
requires something of an investment of time (not that its huge). I
think what slows or stops a new user from jumping into altering the
website (contributing a patch) is that hitting scalate for the first
time it may appear to be more daunting than it is... it definitely is
more work to do, requiring more touch time to get things all together
(just my experience). Perhaps the solution is to create a tutorial on
how to update the site, that explicitly shows a user where to get the
code, how to build/test it, and where to create the JIRA & attach
their patch. Another tutorial should also be made to explain how the
karaf site it put together; I know that during each release I spend
far too much time trying to find all the places I need to update or
append to in the source, vs the old just add page where I want it on
the wiki site (perhaps there is a better way I am unfamiliar with, if
there is please let me know).
Setting up a nightly CI build to deploy the website nightly would help
keep the site more up to date with recent commits. I have to agree
with Christian that updates to the website have been slow getting into
production. I know from my experience setting up to update our webpage
took a bit of messing around, so not having to do that would be a
boost to productivity. This being said do we have a username/password
combo that we can leave on the CI box? The current setup requires
committer credentials to upload/deploy the site, perhaps infra has an
account such as this already created though - we should find out from
them if something like that is available.
Cheers,
Jamie
On Fri, Jun 17, 2011 at 9:12 AM, Guillaume Nodet <gn...@gmail.com> wrote:
> The setup is slightly different as we have two web sites, one for the
> manuals which is versioned and one for the main web site which isn't.
> Things such as committers list, board reports and such aren't really
> tied to a release schedule imho.
>
> On Fri, Jun 17, 2011 at 13:38, James Strachan <ja...@fusesource.com> wrote:
>> BTW we found on the Scalate project we wanted 2 continuous website
>> builds; the current production site branch (i.e. docs for the last
>> major release); so the thing to make http://karaf.apache.org/. Then a
>> continuous build of the new version (trunk);
>> http://karaf.apache.org/versions/3.0-SNAPSHOT (or whatever).
>>
>> Then folks can update the current production website in one branch; or
>> update what will be the next major release (which may be months away);
>> but folks can still view/read the docs for trunk on the website if
>> they want.
>>
>> Also when a release is made, the docs are deployed to a fixed area:
>> http://karaf.apache.org/versions/2.2.3/ or whatever. Then you've just
>> gotta maintain the http://karaf.apache.org/versions/index.html page to
>> link to the various available versions etc.
>>
>>
>> On 17 June 2011 12:28, James Strachan <ja...@fusesource.com> wrote:
>>> On 17 June 2011 12:16, Christian Schneider <ch...@die-schneider.net> wrote:
>>>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>>>
>>>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>>>> the doc without being or becoming committers.
>>>>> I don't want to change a technical decision based on the fact that
>>>>> people *might* need something, but rather what people actually need.
>>>>> You are a committer, so you can access / modify the documentation
>>>>> without any problems. So what are your real problems with the current
>>>>> solution ? We can easily set up nightly uploads or even an hourly
>>>>> cron job (though given the change rate, i think a nightly one should
>>>>> be sufficient). If you need an editor, you always find some software
>>>>> I think such as
>>>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>>>> your changes immediately.
>>>>
>>>> For me as a committer now it is ok. I also do not have problems with editing
>>>> wiki syntax text files by hand. After reading all the comments I think that
>>>> the solution is good for now. I just fear that we might not really attract
>>>> people to help. But you are right people who just work on the documentation
>>>> are rare anyway.
>>>>
>>>> It would be great if we could establish an automatic update of the website
>>>> for trunk and the current production branch. Ideal would be a script like in
>>>> jenkins that only fires when there are real changes then it can be run in
>>>> very short cycles.
>>>
>>> Its really no different from a regular continuous integration build
>>> really; building & deploying the website is just a different mvn
>>> plugin so its like doing snapshot deploy builds.
>>>
>>>
>>>> Btw. How about using jenkins to update the website? The
>>>> update just has to be callable from maven and we have to authenticate in
>>>> some way. Jenkins would also allow to track when and why updates have beem
>>>> done.
>>>
>>> We've been doing this on the Scalate project for a while btw; its just
>>> a matter of setting up a jenkins build in the right branch and using a
>>> profile in the maven build to do the deploy of the website project (as
>>> you probably don't want other builds deploying the website by
>>> default).
>>>
>>> This kinda thing does the trick in the website pom...
>>>
>>> <plugin>
>>> <groupId>org.fusesource.scalate</groupId>
>>> <artifactId>maven-scalate-plugin</artifactId>
>>> <version>${project.version}</version>
>>> <configuration>
>>>
>>> <remoteServerId>people.apache.org</remoteServerId>
>>>
>>> <!-- server stuff here - scp or dav or whatnot... -->
>>> <!-- TODO fixme - i just made this up .... --->
>>> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
>>> </configuration>
>>> <executions>
>>> <execution>
>>> <id>sitegen</id>
>>> <goals>
>>> <goal>sitegen</goal>
>>> </goals>
>>> <phase>package</phase>
>>> </execution>
>>> <execution>
>>> <id>deploy</id>
>>> <goals>
>>> <goal>deploy</goal>
>>> </goals>
>>> <phase>deploy</phase>
>>> </execution>
>>> </executions>
>>> </plugin>
>>>
>>> --
>>> James
>>> -------
>>> FuseSource
>>> Email: james@fusesource.com
>>> Web: http://fusesource.com
>>> Twitter: jstrachan, fusenews
>>> Blog: http://macstrac.blogspot.com/
>>>
>>> Open Source Integration and Messaging
>>>
>>
>>
>>
>> --
>> James
>> -------
>> FuseSource
>> Email: james@fusesource.com
>> Web: http://fusesource.com
>> Twitter: jstrachan, fusenews
>> Blog: http://macstrac.blogspot.com/
>>
>> Open Source Integration and Messaging
>>
>
>
>
> --
> ------------------------
> Guillaume Nodet
> ------------------------
> Blog: http://gnodet.blogspot.com/
> ------------------------
> Open Source SOA
> http://fusesource.com
>
Re: Karaf first birthday concall minute notes
Posted by Achim Nierbeck <bc...@googlemail.com>.
Hi Guillaume,
this might be a good place to put in the wiki, as long as it isn't
disabled. That way we can keep our "non-Versioned" documentation
from beeing updated through a build process (kind of a overhead)
just embed this stuff like the "Roadmap" in the Main Page.
Just my 2 cents :-)
Achim
2011/6/17 Guillaume Nodet <gn...@gmail.com>:
> The setup is slightly different as we have two web sites, one for the
> manuals which is versioned and one for the main web site which isn't.
> Things such as committers list, board reports and such aren't really
> tied to a release schedule imho.
>
> On Fri, Jun 17, 2011 at 13:38, James Strachan <ja...@fusesource.com> wrote:
>> BTW we found on the Scalate project we wanted 2 continuous website
>> builds; the current production site branch (i.e. docs for the last
>> major release); so the thing to make http://karaf.apache.org/. Then a
>> continuous build of the new version (trunk);
>> http://karaf.apache.org/versions/3.0-SNAPSHOT (or whatever).
>>
>> Then folks can update the current production website in one branch; or
>> update what will be the next major release (which may be months away);
>> but folks can still view/read the docs for trunk on the website if
>> they want.
>>
>> Also when a release is made, the docs are deployed to a fixed area:
>> http://karaf.apache.org/versions/2.2.3/ or whatever. Then you've just
>> gotta maintain the http://karaf.apache.org/versions/index.html page to
>> link to the various available versions etc.
>>
>>
>> On 17 June 2011 12:28, James Strachan <ja...@fusesource.com> wrote:
>>> On 17 June 2011 12:16, Christian Schneider <ch...@die-schneider.net> wrote:
>>>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>>>
>>>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>>>> the doc without being or becoming committers.
>>>>> I don't want to change a technical decision based on the fact that
>>>>> people *might* need something, but rather what people actually need.
>>>>> You are a committer, so you can access / modify the documentation
>>>>> without any problems. So what are your real problems with the current
>>>>> solution ? We can easily set up nightly uploads or even an hourly
>>>>> cron job (though given the change rate, i think a nightly one should
>>>>> be sufficient). If you need an editor, you always find some software
>>>>> I think such as
>>>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>>>> your changes immediately.
>>>>
>>>> For me as a committer now it is ok. I also do not have problems with editing
>>>> wiki syntax text files by hand. After reading all the comments I think that
>>>> the solution is good for now. I just fear that we might not really attract
>>>> people to help. But you are right people who just work on the documentation
>>>> are rare anyway.
>>>>
>>>> It would be great if we could establish an automatic update of the website
>>>> for trunk and the current production branch. Ideal would be a script like in
>>>> jenkins that only fires when there are real changes then it can be run in
>>>> very short cycles.
>>>
>>> Its really no different from a regular continuous integration build
>>> really; building & deploying the website is just a different mvn
>>> plugin so its like doing snapshot deploy builds.
>>>
>>>
>>>> Btw. How about using jenkins to update the website? The
>>>> update just has to be callable from maven and we have to authenticate in
>>>> some way. Jenkins would also allow to track when and why updates have beem
>>>> done.
>>>
>>> We've been doing this on the Scalate project for a while btw; its just
>>> a matter of setting up a jenkins build in the right branch and using a
>>> profile in the maven build to do the deploy of the website project (as
>>> you probably don't want other builds deploying the website by
>>> default).
>>>
>>> This kinda thing does the trick in the website pom...
>>>
>>> <plugin>
>>> <groupId>org.fusesource.scalate</groupId>
>>> <artifactId>maven-scalate-plugin</artifactId>
>>> <version>${project.version}</version>
>>> <configuration>
>>>
>>> <remoteServerId>people.apache.org</remoteServerId>
>>>
>>> <!-- server stuff here - scp or dav or whatnot... -->
>>> <!-- TODO fixme - i just made this up .... --->
>>> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
>>> </configuration>
>>> <executions>
>>> <execution>
>>> <id>sitegen</id>
>>> <goals>
>>> <goal>sitegen</goal>
>>> </goals>
>>> <phase>package</phase>
>>> </execution>
>>> <execution>
>>> <id>deploy</id>
>>> <goals>
>>> <goal>deploy</goal>
>>> </goals>
>>> <phase>deploy</phase>
>>> </execution>
>>> </executions>
>>> </plugin>
>>>
>>> --
>>> James
>>> -------
>>> FuseSource
>>> Email: james@fusesource.com
>>> Web: http://fusesource.com
>>> Twitter: jstrachan, fusenews
>>> Blog: http://macstrac.blogspot.com/
>>>
>>> Open Source Integration and Messaging
>>>
>>
>>
>>
>> --
>> James
>> -------
>> FuseSource
>> Email: james@fusesource.com
>> Web: http://fusesource.com
>> Twitter: jstrachan, fusenews
>> Blog: http://macstrac.blogspot.com/
>>
>> Open Source Integration and Messaging
>>
>
>
>
> --
> ------------------------
> Guillaume Nodet
> ------------------------
> Blog: http://gnodet.blogspot.com/
> ------------------------
> Open Source SOA
> http://fusesource.com
>
--
--
*Achim Nierbeck*
Apache Karaf <http://karaf.apache.org/> Committer & PMC
OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/>
Committer & Project Lead
Re: Karaf first birthday concall minute notes
Posted by Guillaume Nodet <gn...@gmail.com>.
The setup is slightly different as we have two web sites, one for the
manuals which is versioned and one for the main web site which isn't.
Things such as committers list, board reports and such aren't really
tied to a release schedule imho.
On Fri, Jun 17, 2011 at 13:38, James Strachan <ja...@fusesource.com> wrote:
> BTW we found on the Scalate project we wanted 2 continuous website
> builds; the current production site branch (i.e. docs for the last
> major release); so the thing to make http://karaf.apache.org/. Then a
> continuous build of the new version (trunk);
> http://karaf.apache.org/versions/3.0-SNAPSHOT (or whatever).
>
> Then folks can update the current production website in one branch; or
> update what will be the next major release (which may be months away);
> but folks can still view/read the docs for trunk on the website if
> they want.
>
> Also when a release is made, the docs are deployed to a fixed area:
> http://karaf.apache.org/versions/2.2.3/ or whatever. Then you've just
> gotta maintain the http://karaf.apache.org/versions/index.html page to
> link to the various available versions etc.
>
>
> On 17 June 2011 12:28, James Strachan <ja...@fusesource.com> wrote:
>> On 17 June 2011 12:16, Christian Schneider <ch...@die-schneider.net> wrote:
>>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>>
>>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>>> the doc without being or becoming committers.
>>>> I don't want to change a technical decision based on the fact that
>>>> people *might* need something, but rather what people actually need.
>>>> You are a committer, so you can access / modify the documentation
>>>> without any problems. So what are your real problems with the current
>>>> solution ? We can easily set up nightly uploads or even an hourly
>>>> cron job (though given the change rate, i think a nightly one should
>>>> be sufficient). If you need an editor, you always find some software
>>>> I think such as
>>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>>> your changes immediately.
>>>
>>> For me as a committer now it is ok. I also do not have problems with editing
>>> wiki syntax text files by hand. After reading all the comments I think that
>>> the solution is good for now. I just fear that we might not really attract
>>> people to help. But you are right people who just work on the documentation
>>> are rare anyway.
>>>
>>> It would be great if we could establish an automatic update of the website
>>> for trunk and the current production branch. Ideal would be a script like in
>>> jenkins that only fires when there are real changes then it can be run in
>>> very short cycles.
>>
>> Its really no different from a regular continuous integration build
>> really; building & deploying the website is just a different mvn
>> plugin so its like doing snapshot deploy builds.
>>
>>
>>> Btw. How about using jenkins to update the website? The
>>> update just has to be callable from maven and we have to authenticate in
>>> some way. Jenkins would also allow to track when and why updates have beem
>>> done.
>>
>> We've been doing this on the Scalate project for a while btw; its just
>> a matter of setting up a jenkins build in the right branch and using a
>> profile in the maven build to do the deploy of the website project (as
>> you probably don't want other builds deploying the website by
>> default).
>>
>> This kinda thing does the trick in the website pom...
>>
>> <plugin>
>> <groupId>org.fusesource.scalate</groupId>
>> <artifactId>maven-scalate-plugin</artifactId>
>> <version>${project.version}</version>
>> <configuration>
>>
>> <remoteServerId>people.apache.org</remoteServerId>
>>
>> <!-- server stuff here - scp or dav or whatnot... -->
>> <!-- TODO fixme - i just made this up .... --->
>> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
>> </configuration>
>> <executions>
>> <execution>
>> <id>sitegen</id>
>> <goals>
>> <goal>sitegen</goal>
>> </goals>
>> <phase>package</phase>
>> </execution>
>> <execution>
>> <id>deploy</id>
>> <goals>
>> <goal>deploy</goal>
>> </goals>
>> <phase>deploy</phase>
>> </execution>
>> </executions>
>> </plugin>
>>
>> --
>> James
>> -------
>> FuseSource
>> Email: james@fusesource.com
>> Web: http://fusesource.com
>> Twitter: jstrachan, fusenews
>> Blog: http://macstrac.blogspot.com/
>>
>> Open Source Integration and Messaging
>>
>
>
>
> --
> James
> -------
> FuseSource
> Email: james@fusesource.com
> Web: http://fusesource.com
> Twitter: jstrachan, fusenews
> Blog: http://macstrac.blogspot.com/
>
> Open Source Integration and Messaging
>
--
------------------------
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com
Re: Karaf first birthday concall minute notes
Posted by Andreas Pieber <an...@gmail.com>.
would be quite useful if the nightly builds really work! Definitely +1
for the hudson setup
On Fri, Jun 17, 2011 at 1:38 PM, James Strachan <ja...@fusesource.com> wrote:
> BTW we found on the Scalate project we wanted 2 continuous website
> builds; the current production site branch (i.e. docs for the last
> major release); so the thing to make http://karaf.apache.org/. Then a
> continuous build of the new version (trunk);
> http://karaf.apache.org/versions/3.0-SNAPSHOT (or whatever).
>
> Then folks can update the current production website in one branch; or
> update what will be the next major release (which may be months away);
> but folks can still view/read the docs for trunk on the website if
> they want.
>
> Also when a release is made, the docs are deployed to a fixed area:
> http://karaf.apache.org/versions/2.2.3/ or whatever. Then you've just
> gotta maintain the http://karaf.apache.org/versions/index.html page to
> link to the various available versions etc.
>
>
> On 17 June 2011 12:28, James Strachan <ja...@fusesource.com> wrote:
>> On 17 June 2011 12:16, Christian Schneider <ch...@die-schneider.net> wrote:
>>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>>
>>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>>> the doc without being or becoming committers.
>>>> I don't want to change a technical decision based on the fact that
>>>> people *might* need something, but rather what people actually need.
>>>> You are a committer, so you can access / modify the documentation
>>>> without any problems. So what are your real problems with the current
>>>> solution ? We can easily set up nightly uploads or even an hourly
>>>> cron job (though given the change rate, i think a nightly one should
>>>> be sufficient). If you need an editor, you always find some software
>>>> I think such as
>>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>>> your changes immediately.
>>>
>>> For me as a committer now it is ok. I also do not have problems with editing
>>> wiki syntax text files by hand. After reading all the comments I think that
>>> the solution is good for now. I just fear that we might not really attract
>>> people to help. But you are right people who just work on the documentation
>>> are rare anyway.
>>>
>>> It would be great if we could establish an automatic update of the website
>>> for trunk and the current production branch. Ideal would be a script like in
>>> jenkins that only fires when there are real changes then it can be run in
>>> very short cycles.
>>
>> Its really no different from a regular continuous integration build
>> really; building & deploying the website is just a different mvn
>> plugin so its like doing snapshot deploy builds.
>>
>>
>>> Btw. How about using jenkins to update the website? The
>>> update just has to be callable from maven and we have to authenticate in
>>> some way. Jenkins would also allow to track when and why updates have beem
>>> done.
>>
>> We've been doing this on the Scalate project for a while btw; its just
>> a matter of setting up a jenkins build in the right branch and using a
>> profile in the maven build to do the deploy of the website project (as
>> you probably don't want other builds deploying the website by
>> default).
>>
>> This kinda thing does the trick in the website pom...
>>
>> <plugin>
>> <groupId>org.fusesource.scalate</groupId>
>> <artifactId>maven-scalate-plugin</artifactId>
>> <version>${project.version}</version>
>> <configuration>
>>
>> <remoteServerId>people.apache.org</remoteServerId>
>>
>> <!-- server stuff here - scp or dav or whatnot... -->
>> <!-- TODO fixme - i just made this up .... --->
>> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
>> </configuration>
>> <executions>
>> <execution>
>> <id>sitegen</id>
>> <goals>
>> <goal>sitegen</goal>
>> </goals>
>> <phase>package</phase>
>> </execution>
>> <execution>
>> <id>deploy</id>
>> <goals>
>> <goal>deploy</goal>
>> </goals>
>> <phase>deploy</phase>
>> </execution>
>> </executions>
>> </plugin>
>>
>> --
>> James
>> -------
>> FuseSource
>> Email: james@fusesource.com
>> Web: http://fusesource.com
>> Twitter: jstrachan, fusenews
>> Blog: http://macstrac.blogspot.com/
>>
>> Open Source Integration and Messaging
>>
>
>
>
> --
> James
> -------
> FuseSource
> Email: james@fusesource.com
> Web: http://fusesource.com
> Twitter: jstrachan, fusenews
> Blog: http://macstrac.blogspot.com/
>
> Open Source Integration and Messaging
>
Re: Karaf first birthday concall minute notes
Posted by James Strachan <ja...@fusesource.com>.
BTW we found on the Scalate project we wanted 2 continuous website
builds; the current production site branch (i.e. docs for the last
major release); so the thing to make http://karaf.apache.org/. Then a
continuous build of the new version (trunk);
http://karaf.apache.org/versions/3.0-SNAPSHOT (or whatever).
Then folks can update the current production website in one branch; or
update what will be the next major release (which may be months away);
but folks can still view/read the docs for trunk on the website if
they want.
Also when a release is made, the docs are deployed to a fixed area:
http://karaf.apache.org/versions/2.2.3/ or whatever. Then you've just
gotta maintain the http://karaf.apache.org/versions/index.html page to
link to the various available versions etc.
On 17 June 2011 12:28, James Strachan <ja...@fusesource.com> wrote:
> On 17 June 2011 12:16, Christian Schneider <ch...@die-schneider.net> wrote:
>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>
>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>> the doc without being or becoming committers.
>>> I don't want to change a technical decision based on the fact that
>>> people *might* need something, but rather what people actually need.
>>> You are a committer, so you can access / modify the documentation
>>> without any problems. So what are your real problems with the current
>>> solution ? We can easily set up nightly uploads or even an hourly
>>> cron job (though given the change rate, i think a nightly one should
>>> be sufficient). If you need an editor, you always find some software
>>> I think such as
>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>> your changes immediately.
>>
>> For me as a committer now it is ok. I also do not have problems with editing
>> wiki syntax text files by hand. After reading all the comments I think that
>> the solution is good for now. I just fear that we might not really attract
>> people to help. But you are right people who just work on the documentation
>> are rare anyway.
>>
>> It would be great if we could establish an automatic update of the website
>> for trunk and the current production branch. Ideal would be a script like in
>> jenkins that only fires when there are real changes then it can be run in
>> very short cycles.
>
> Its really no different from a regular continuous integration build
> really; building & deploying the website is just a different mvn
> plugin so its like doing snapshot deploy builds.
>
>
>> Btw. How about using jenkins to update the website? The
>> update just has to be callable from maven and we have to authenticate in
>> some way. Jenkins would also allow to track when and why updates have beem
>> done.
>
> We've been doing this on the Scalate project for a while btw; its just
> a matter of setting up a jenkins build in the right branch and using a
> profile in the maven build to do the deploy of the website project (as
> you probably don't want other builds deploying the website by
> default).
>
> This kinda thing does the trick in the website pom...
>
> <plugin>
> <groupId>org.fusesource.scalate</groupId>
> <artifactId>maven-scalate-plugin</artifactId>
> <version>${project.version}</version>
> <configuration>
>
> <remoteServerId>people.apache.org</remoteServerId>
>
> <!-- server stuff here - scp or dav or whatnot... -->
> <!-- TODO fixme - i just made this up .... --->
> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
> </configuration>
> <executions>
> <execution>
> <id>sitegen</id>
> <goals>
> <goal>sitegen</goal>
> </goals>
> <phase>package</phase>
> </execution>
> <execution>
> <id>deploy</id>
> <goals>
> <goal>deploy</goal>
> </goals>
> <phase>deploy</phase>
> </execution>
> </executions>
> </plugin>
>
> --
> James
> -------
> FuseSource
> Email: james@fusesource.com
> Web: http://fusesource.com
> Twitter: jstrachan, fusenews
> Blog: http://macstrac.blogspot.com/
>
> Open Source Integration and Messaging
>
--
James
-------
FuseSource
Email: james@fusesource.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration and Messaging
Re: Karaf first birthday concall minute notes
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
+1,
and we can also add a maven goal execution to update website/manual.
Regards
JB
On 06/17/2011 01:35 PM, Guillaume Nodet wrote:
> Yeah, I think everything is already setup correctly, we just need to
> add the nightly builds to the CI system.
>
> On Fri, Jun 17, 2011 at 13:28, James Strachan<ja...@fusesource.com> wrote:
>> On 17 June 2011 12:16, Christian Schneider<ch...@die-schneider.net> wrote:
>>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>>
>>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>>> the doc without being or becoming committers.
>>>> I don't want to change a technical decision based on the fact that
>>>> people *might* need something, but rather what people actually need.
>>>> You are a committer, so you can access / modify the documentation
>>>> without any problems. So what are your real problems with the current
>>>> solution ? We can easily set up nightly uploads or even an hourly
>>>> cron job (though given the change rate, i think a nightly one should
>>>> be sufficient). If you need an editor, you always find some software
>>>> I think such as
>>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>>> your changes immediately.
>>>
>>> For me as a committer now it is ok. I also do not have problems with editing
>>> wiki syntax text files by hand. After reading all the comments I think that
>>> the solution is good for now. I just fear that we might not really attract
>>> people to help. But you are right people who just work on the documentation
>>> are rare anyway.
>>>
>>> It would be great if we could establish an automatic update of the website
>>> for trunk and the current production branch. Ideal would be a script like in
>>> jenkins that only fires when there are real changes then it can be run in
>>> very short cycles.
>>
>> Its really no different from a regular continuous integration build
>> really; building& deploying the website is just a different mvn
>> plugin so its like doing snapshot deploy builds.
>>
>>
>>> Btw. How about using jenkins to update the website? The
>>> update just has to be callable from maven and we have to authenticate in
>>> some way. Jenkins would also allow to track when and why updates have beem
>>> done.
>>
>> We've been doing this on the Scalate project for a while btw; its just
>> a matter of setting up a jenkins build in the right branch and using a
>> profile in the maven build to do the deploy of the website project (as
>> you probably don't want other builds deploying the website by
>> default).
>>
>> This kinda thing does the trick in the website pom...
>>
>> <plugin>
>> <groupId>org.fusesource.scalate</groupId>
>> <artifactId>maven-scalate-plugin</artifactId>
>> <version>${project.version}</version>
>> <configuration>
>>
>> <remoteServerId>people.apache.org</remoteServerId>
>>
>> <!-- server stuff here - scp or dav or whatnot... -->
>> <!-- TODO fixme - i just made this up .... --->
>> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
>> </configuration>
>> <executions>
>> <execution>
>> <id>sitegen</id>
>> <goals>
>> <goal>sitegen</goal>
>> </goals>
>> <phase>package</phase>
>> </execution>
>> <execution>
>> <id>deploy</id>
>> <goals>
>> <goal>deploy</goal>
>> </goals>
>> <phase>deploy</phase>
>> </execution>
>> </executions>
>> </plugin>
>>
>> --
>> James
>> -------
>> FuseSource
>> Email: james@fusesource.com
>> Web: http://fusesource.com
>> Twitter: jstrachan, fusenews
>> Blog: http://macstrac.blogspot.com/
>>
>> Open Source Integration and Messaging
>>
>
>
>
Re: Karaf first birthday concall minute notes
Posted by Guillaume Nodet <gn...@gmail.com>.
Yeah, I think everything is already setup correctly, we just need to
add the nightly builds to the CI system.
On Fri, Jun 17, 2011 at 13:28, James Strachan <ja...@fusesource.com> wrote:
> On 17 June 2011 12:16, Christian Schneider <ch...@die-schneider.net> wrote:
>> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>>
>>> Over the last 5 years, I've rarely seen people contributing a lot to
>>> the doc without being or becoming committers.
>>> I don't want to change a technical decision based on the fact that
>>> people *might* need something, but rather what people actually need.
>>> You are a committer, so you can access / modify the documentation
>>> without any problems. So what are your real problems with the current
>>> solution ? We can easily set up nightly uploads or even an hourly
>>> cron job (though given the change rate, i think a nightly one should
>>> be sufficient). If you need an editor, you always find some software
>>> I think such as
>>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>>> tend to use the "mvn jetty:run" which works quite well as you can see
>>> your changes immediately.
>>
>> For me as a committer now it is ok. I also do not have problems with editing
>> wiki syntax text files by hand. After reading all the comments I think that
>> the solution is good for now. I just fear that we might not really attract
>> people to help. But you are right people who just work on the documentation
>> are rare anyway.
>>
>> It would be great if we could establish an automatic update of the website
>> for trunk and the current production branch. Ideal would be a script like in
>> jenkins that only fires when there are real changes then it can be run in
>> very short cycles.
>
> Its really no different from a regular continuous integration build
> really; building & deploying the website is just a different mvn
> plugin so its like doing snapshot deploy builds.
>
>
>> Btw. How about using jenkins to update the website? The
>> update just has to be callable from maven and we have to authenticate in
>> some way. Jenkins would also allow to track when and why updates have beem
>> done.
>
> We've been doing this on the Scalate project for a while btw; its just
> a matter of setting up a jenkins build in the right branch and using a
> profile in the maven build to do the deploy of the website project (as
> you probably don't want other builds deploying the website by
> default).
>
> This kinda thing does the trick in the website pom...
>
> <plugin>
> <groupId>org.fusesource.scalate</groupId>
> <artifactId>maven-scalate-plugin</artifactId>
> <version>${project.version}</version>
> <configuration>
>
> <remoteServerId>people.apache.org</remoteServerId>
>
> <!-- server stuff here - scp or dav or whatnot... -->
> <!-- TODO fixme - i just made this up .... --->
> <remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
> </configuration>
> <executions>
> <execution>
> <id>sitegen</id>
> <goals>
> <goal>sitegen</goal>
> </goals>
> <phase>package</phase>
> </execution>
> <execution>
> <id>deploy</id>
> <goals>
> <goal>deploy</goal>
> </goals>
> <phase>deploy</phase>
> </execution>
> </executions>
> </plugin>
>
> --
> James
> -------
> FuseSource
> Email: james@fusesource.com
> Web: http://fusesource.com
> Twitter: jstrachan, fusenews
> Blog: http://macstrac.blogspot.com/
>
> Open Source Integration and Messaging
>
--
------------------------
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com
Re: Karaf first birthday concall minute notes
Posted by James Strachan <ja...@fusesource.com>.
On 17 June 2011 12:16, Christian Schneider <ch...@die-schneider.net> wrote:
> Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>>
>> Over the last 5 years, I've rarely seen people contributing a lot to
>> the doc without being or becoming committers.
>> I don't want to change a technical decision based on the fact that
>> people *might* need something, but rather what people actually need.
>> You are a committer, so you can access / modify the documentation
>> without any problems. So what are your real problems with the current
>> solution ? We can easily set up nightly uploads or even an hourly
>> cron job (though given the change rate, i think a nightly one should
>> be sufficient). If you need an editor, you always find some software
>> I think such as
>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>> tend to use the "mvn jetty:run" which works quite well as you can see
>> your changes immediately.
>
> For me as a committer now it is ok. I also do not have problems with editing
> wiki syntax text files by hand. After reading all the comments I think that
> the solution is good for now. I just fear that we might not really attract
> people to help. But you are right people who just work on the documentation
> are rare anyway.
>
> It would be great if we could establish an automatic update of the website
> for trunk and the current production branch. Ideal would be a script like in
> jenkins that only fires when there are real changes then it can be run in
> very short cycles.
Its really no different from a regular continuous integration build
really; building & deploying the website is just a different mvn
plugin so its like doing snapshot deploy builds.
> Btw. How about using jenkins to update the website? The
> update just has to be callable from maven and we have to authenticate in
> some way. Jenkins would also allow to track when and why updates have beem
> done.
We've been doing this on the Scalate project for a while btw; its just
a matter of setting up a jenkins build in the right branch and using a
profile in the maven build to do the deploy of the website project (as
you probably don't want other builds deploying the website by
default).
This kinda thing does the trick in the website pom...
<plugin>
<groupId>org.fusesource.scalate</groupId>
<artifactId>maven-scalate-plugin</artifactId>
<version>${project.version}</version>
<configuration>
<remoteServerId>people.apache.org</remoteServerId>
<!-- server stuff here - scp or dav or whatnot... -->
<!-- TODO fixme - i just made this up .... --->
<remoteServerUrl>scp:people.apache.org:/www/karaf.apache.org/versions/${project.version}</remoteServerUrl>
</configuration>
<executions>
<execution>
<id>sitegen</id>
<goals>
<goal>sitegen</goal>
</goals>
<phase>package</phase>
</execution>
<execution>
<id>deploy</id>
<goals>
<goal>deploy</goal>
</goals>
<phase>deploy</phase>
</execution>
</executions>
</plugin>
--
James
-------
FuseSource
Email: james@fusesource.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration and Messaging
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
Am 17.06.2011 12:53, schrieb Guillaume Nodet:
>
> Over the last 5 years, I've rarely seen people contributing a lot to
> the doc without being or becoming committers.
> I don't want to change a technical decision based on the fact that
> people *might* need something, but rather what people actually need.
> You are a committer, so you can access / modify the documentation
> without any problems. So what are your real problems with the current
> solution ? We can easily set up nightly uploads or even an hourly
> cron job (though given the change rate, i think a nightly one should
> be sufficient). If you need an editor, you always find some software
> I think such as
> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
> tend to use the "mvn jetty:run" which works quite well as you can see
> your changes immediately.
For me as a committer now it is ok. I also do not have problems with
editing wiki syntax text files by hand. After reading all the comments I
think that
the solution is good for now. I just fear that we might not really
attract people to help. But you are right people who just work on the
documentation are rare anyway.
It would be great if we could establish an automatic update of the
website for trunk and the current production branch. Ideal would be a
script like in jenkins that only fires when there are real changes then
it can be run in very short cycles. Btw. How about using jenkins to
update the website? The update just has to be callable from maven and we
have to authenticate in some way. Jenkins would also allow to track when
and why updates have beem done.
> The main problem is that we've been asked by infra to get rid of
> confluence, so I certainly don't want to think about getting back to
> confluence unless infra retracts.
Yes I also heard about this. I would really like to know what the plans
are in respect to confluence.
Christian
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
+1
Yes I would also like to have a nightly build of the documentation from
trunk.
Additionally we should have a nightly build of the current production
branch (2.x in our case).
A build of the docs on release is also good but I think more important
is the branch as this allows us to fix problems in the documentation
after a release.
Christian
Am 17.06.2011 13:23, schrieb Achim Nierbeck:
> Hey,
>
> I like that idea of a nightly build on documentation :-)
> If we get this easily integrated on our karaf.apache.org
> with the right hint that it's the last documentation from trunk.
> Voila done :-)
>
> regards, Achim
>
> 2011/6/17 Guillaume Nodet<gn...@gmail.com>:
>> On Fri, Jun 17, 2011 at 12:28, James Strachan<ja...@fusesource.com> wrote:
>>> On 17 June 2011 11:16, Christian Schneider<ch...@die-schneider.net> wrote:
>>>> Hi James,
>>>>
>>>> first thanks for your explanations.
>>>>
>>>> Am 17.06.2011 11:14, schrieb James Strachan:
>>>>> On 17 June 2011 09:19, Christian Schneider<ch...@die-schneider.net>
>>>>> wrote:
>>>>>> I know that I have proposed this before and then got the answer that this
>>>>>> was discussed already. Still I have the feeling that everybody dislikes
>>>>>> the
>>>>>> current way we build our website.... so again a try :-)...
>>>>> I'm not sure you realise how much dislike there is for wikis?
>>>>>
>>>> I did not realize but I am starting to see :-) I only saw the
>>>>> Wikis don't help committers and don't help users (as you end up with
>>>>> crap everywhere from different versions - or worse documentation for
>>>>> stuff thats not even released yet); all just in case we hope one day
>>>>> someone will turn up and dump a load of useful stuff in the wiki (that
>>>>> never really happens).
>>>> That is true help from people outside the project is rare.
>>>>> Incidentally I'm even finding the argument that a wiki is the easiest
>>>>> way to get contributions to have less and less value these days since
>>>>> github. Its actually easier for a total newbie to come along, fork an
>>>>> apache project's git repo on github.com, edit some text files& do a
>>>>> pull request than it is to pester folks for write access to the wiki
>>>>> first before they can even begin to contribute anything. The wiki has
>>>>> a much larger barrier to entry than github.
>>>> Github would be a great way to improve the documentation workflow for karaf.
>>>> You would not
>>>> need to open a jira issue to make a change and apply patch. Sadly we are
>>>> stuck with subversion.
>>> Sure - the sooner we can ditch subversion at Apache the better.
>>> However still the easiest way to get new documentation contributions
>>> today at Apache is to get folks to fork the apache repos at github.
>>> Then asynchronously do the ICLA stuff; not block on the ICLA first.
>>>
>>>
>>>
>>>>> Imagine for a second, you are a newbie - you've seen some issue or
>>>>> have an idea for a little page; with github 2 clicks, 20 seconds later
>>>>> you're editing the file in question or writing the new file then
>>>>> firing off the pull request and getting on with your life doing
>>>>> something else. With a wiki you try editing; doesn't work, so you
>>>>> shoot off an email for access then wait. Then after a random time
>>>>> period of hours to days you get more mails then at some point later,
>>>>> you get the ability to login again to the wiki and hopefully you can
>>>>> now edit the page. By the time you get access you've probably
>>>>> forgotten what you were gonna do in the first place :)
>>>> The process of getting rights for the wiki is a problem of course. But it is
>>>> necesary as we need the icla to accept contributions.
>>>> That may also be a big problem with github. You send a pull request but that
>>>> opens a big problem with IP issues. I think a pull request
>>>> does not include that the user declares that he has the rights on the code
>>>> he submits and may donate them to apache. In fact it does not even say he
>>>> donates the code at all.
>>>> So for example offering dual licenses later is a problem. I think this is a
>>>> big issue with github. I am not sure how important this is for documentation
>>>> though.
>>> We need the ICLA before we can merge into our repo. However thats a
>>> completely separate issue to the potential new contributor being able
>>> to actually create their contribution in the first place. The ICLA
>>> stuff can be done in parallel after their initial contribution and it
>>> really doesn't matter if it takes weeks to do (which it usually does
>>> anyway). Apache committers are the only ones who merge the github
>>> changes to the Apache repos - so there is zero issue of IP here.
>>>
>>> Whats important is folks can contribute quickly and easily with
>>> minimum delay or red tape. We're all busy; if you have to wait 2-3
>>> weeks before you can add a line of text to a document; you're gonna
>>> find something else to do quite frankly. Waiting weeks for an ICLA
>>> does not make it easy for newbies to contribute. With github they can
>>> make their contributions immediately; folks can immediately see it and
>>> comment on it. Then in parallel work can commence on getting the ICLA
>>> in place so the changes can be merged to Apache. Indeed while the ICLA
>>> is being processed the user can make more contributions. When the ICLA
>>> is done then a committer can merge in whatever documentation changes
>>> they've made.
>> Over the last 5 years, I've rarely seen people contributing a lot to
>> the doc without being or becoming committers.
>> I don't want to change a technical decision based on the fact that
>> people *might* need something, but rather what people actually need.
>> You are a committer, so you can access / modify the documentation
>> without any problems. So what are your real problems with the current
>> solution ? We can easily set up nightly uploads or even an hourly
>> cron job (though given the change rate, i think a nightly one should
>> be sufficient). If you need an editor, you always find some software
>> I think such as
>> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
>> tend to use the "mvn jetty:run" which works quite well as you can see
>> your changes immediately.
>>
>> The main problem is that we've been asked by infra to get rid of
>> confluence, so I certainly don't want to think about getting back to
>> confluence unless infra retracts.
>>
>>> --
>>> James
>>> -------
>>> FuseSource
>>> Email: james@fusesource.com
>>> Web: http://fusesource.com
>>> Twitter: jstrachan, fusenews
>>> Blog: http://macstrac.blogspot.com/
>>>
>>> Open Source Integration and Messaging
>>>
>>
>>
>> --
>> ------------------------
>> Guillaume Nodet
>> ------------------------
>> Blog: http://gnodet.blogspot.com/
>> ------------------------
>> Open Source SOA
>> http://fusesource.com
>>
>
>
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by Achim Nierbeck <bc...@googlemail.com>.
Hey,
I like that idea of a nightly build on documentation :-)
If we get this easily integrated on our karaf.apache.org
with the right hint that it's the last documentation from trunk.
Voila done :-)
regards, Achim
2011/6/17 Guillaume Nodet <gn...@gmail.com>:
> On Fri, Jun 17, 2011 at 12:28, James Strachan <ja...@fusesource.com> wrote:
>> On 17 June 2011 11:16, Christian Schneider <ch...@die-schneider.net> wrote:
>>> Hi James,
>>>
>>> first thanks for your explanations.
>>>
>>> Am 17.06.2011 11:14, schrieb James Strachan:
>>>>
>>>> On 17 June 2011 09:19, Christian Schneider<ch...@die-schneider.net>
>>>> wrote:
>>>>>
>>>>> I know that I have proposed this before and then got the answer that this
>>>>> was discussed already. Still I have the feeling that everybody dislikes
>>>>> the
>>>>> current way we build our website.... so again a try :-)...
>>>>
>>>> I'm not sure you realise how much dislike there is for wikis?
>>>>
>>> I did not realize but I am starting to see :-) I only saw the
>>>>
>>>> Wikis don't help committers and don't help users (as you end up with
>>>> crap everywhere from different versions - or worse documentation for
>>>> stuff thats not even released yet); all just in case we hope one day
>>>> someone will turn up and dump a load of useful stuff in the wiki (that
>>>> never really happens).
>>>
>>> That is true help from people outside the project is rare.
>>>>
>>>> Incidentally I'm even finding the argument that a wiki is the easiest
>>>> way to get contributions to have less and less value these days since
>>>> github. Its actually easier for a total newbie to come along, fork an
>>>> apache project's git repo on github.com, edit some text files& do a
>>>> pull request than it is to pester folks for write access to the wiki
>>>> first before they can even begin to contribute anything. The wiki has
>>>> a much larger barrier to entry than github.
>>>
>>> Github would be a great way to improve the documentation workflow for karaf.
>>> You would not
>>> need to open a jira issue to make a change and apply patch. Sadly we are
>>> stuck with subversion.
>>
>> Sure - the sooner we can ditch subversion at Apache the better.
>> However still the easiest way to get new documentation contributions
>> today at Apache is to get folks to fork the apache repos at github.
>> Then asynchronously do the ICLA stuff; not block on the ICLA first.
>>
>>
>>
>>>> Imagine for a second, you are a newbie - you've seen some issue or
>>>> have an idea for a little page; with github 2 clicks, 20 seconds later
>>>> you're editing the file in question or writing the new file then
>>>> firing off the pull request and getting on with your life doing
>>>> something else. With a wiki you try editing; doesn't work, so you
>>>> shoot off an email for access then wait. Then after a random time
>>>> period of hours to days you get more mails then at some point later,
>>>> you get the ability to login again to the wiki and hopefully you can
>>>> now edit the page. By the time you get access you've probably
>>>> forgotten what you were gonna do in the first place :)
>>>
>>> The process of getting rights for the wiki is a problem of course. But it is
>>> necesary as we need the icla to accept contributions.
>>> That may also be a big problem with github. You send a pull request but that
>>> opens a big problem with IP issues. I think a pull request
>>> does not include that the user declares that he has the rights on the code
>>> he submits and may donate them to apache. In fact it does not even say he
>>> donates the code at all.
>>> So for example offering dual licenses later is a problem. I think this is a
>>> big issue with github. I am not sure how important this is for documentation
>>> though.
>>
>> We need the ICLA before we can merge into our repo. However thats a
>> completely separate issue to the potential new contributor being able
>> to actually create their contribution in the first place. The ICLA
>> stuff can be done in parallel after their initial contribution and it
>> really doesn't matter if it takes weeks to do (which it usually does
>> anyway). Apache committers are the only ones who merge the github
>> changes to the Apache repos - so there is zero issue of IP here.
>>
>> Whats important is folks can contribute quickly and easily with
>> minimum delay or red tape. We're all busy; if you have to wait 2-3
>> weeks before you can add a line of text to a document; you're gonna
>> find something else to do quite frankly. Waiting weeks for an ICLA
>> does not make it easy for newbies to contribute. With github they can
>> make their contributions immediately; folks can immediately see it and
>> comment on it. Then in parallel work can commence on getting the ICLA
>> in place so the changes can be merged to Apache. Indeed while the ICLA
>> is being processed the user can make more contributions. When the ICLA
>> is done then a committer can merge in whatever documentation changes
>> they've made.
>
> Over the last 5 years, I've rarely seen people contributing a lot to
> the doc without being or becoming committers.
> I don't want to change a technical decision based on the fact that
> people *might* need something, but rather what people actually need.
> You are a committer, so you can access / modify the documentation
> without any problems. So what are your real problems with the current
> solution ? We can easily set up nightly uploads or even an hourly
> cron job (though given the change rate, i think a nightly one should
> be sufficient). If you need an editor, you always find some software
> I think such as
> http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
> tend to use the "mvn jetty:run" which works quite well as you can see
> your changes immediately.
>
> The main problem is that we've been asked by infra to get rid of
> confluence, so I certainly don't want to think about getting back to
> confluence unless infra retracts.
>
>>
>> --
>> James
>> -------
>> FuseSource
>> Email: james@fusesource.com
>> Web: http://fusesource.com
>> Twitter: jstrachan, fusenews
>> Blog: http://macstrac.blogspot.com/
>>
>> Open Source Integration and Messaging
>>
>
>
>
> --
> ------------------------
> Guillaume Nodet
> ------------------------
> Blog: http://gnodet.blogspot.com/
> ------------------------
> Open Source SOA
> http://fusesource.com
>
--
--
*Achim Nierbeck*
Apache Karaf <http://karaf.apache.org/> Committer & PMC
OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/>
Committer & Project Lead
Re: Karaf first birthday concall minute notes
Posted by Guillaume Nodet <gn...@gmail.com>.
On Fri, Jun 17, 2011 at 12:28, James Strachan <ja...@fusesource.com> wrote:
> On 17 June 2011 11:16, Christian Schneider <ch...@die-schneider.net> wrote:
>> Hi James,
>>
>> first thanks for your explanations.
>>
>> Am 17.06.2011 11:14, schrieb James Strachan:
>>>
>>> On 17 June 2011 09:19, Christian Schneider<ch...@die-schneider.net>
>>> wrote:
>>>>
>>>> I know that I have proposed this before and then got the answer that this
>>>> was discussed already. Still I have the feeling that everybody dislikes
>>>> the
>>>> current way we build our website.... so again a try :-)...
>>>
>>> I'm not sure you realise how much dislike there is for wikis?
>>>
>> I did not realize but I am starting to see :-) I only saw the
>>>
>>> Wikis don't help committers and don't help users (as you end up with
>>> crap everywhere from different versions - or worse documentation for
>>> stuff thats not even released yet); all just in case we hope one day
>>> someone will turn up and dump a load of useful stuff in the wiki (that
>>> never really happens).
>>
>> That is true help from people outside the project is rare.
>>>
>>> Incidentally I'm even finding the argument that a wiki is the easiest
>>> way to get contributions to have less and less value these days since
>>> github. Its actually easier for a total newbie to come along, fork an
>>> apache project's git repo on github.com, edit some text files& do a
>>> pull request than it is to pester folks for write access to the wiki
>>> first before they can even begin to contribute anything. The wiki has
>>> a much larger barrier to entry than github.
>>
>> Github would be a great way to improve the documentation workflow for karaf.
>> You would not
>> need to open a jira issue to make a change and apply patch. Sadly we are
>> stuck with subversion.
>
> Sure - the sooner we can ditch subversion at Apache the better.
> However still the easiest way to get new documentation contributions
> today at Apache is to get folks to fork the apache repos at github.
> Then asynchronously do the ICLA stuff; not block on the ICLA first.
>
>
>
>>> Imagine for a second, you are a newbie - you've seen some issue or
>>> have an idea for a little page; with github 2 clicks, 20 seconds later
>>> you're editing the file in question or writing the new file then
>>> firing off the pull request and getting on with your life doing
>>> something else. With a wiki you try editing; doesn't work, so you
>>> shoot off an email for access then wait. Then after a random time
>>> period of hours to days you get more mails then at some point later,
>>> you get the ability to login again to the wiki and hopefully you can
>>> now edit the page. By the time you get access you've probably
>>> forgotten what you were gonna do in the first place :)
>>
>> The process of getting rights for the wiki is a problem of course. But it is
>> necesary as we need the icla to accept contributions.
>> That may also be a big problem with github. You send a pull request but that
>> opens a big problem with IP issues. I think a pull request
>> does not include that the user declares that he has the rights on the code
>> he submits and may donate them to apache. In fact it does not even say he
>> donates the code at all.
>> So for example offering dual licenses later is a problem. I think this is a
>> big issue with github. I am not sure how important this is for documentation
>> though.
>
> We need the ICLA before we can merge into our repo. However thats a
> completely separate issue to the potential new contributor being able
> to actually create their contribution in the first place. The ICLA
> stuff can be done in parallel after their initial contribution and it
> really doesn't matter if it takes weeks to do (which it usually does
> anyway). Apache committers are the only ones who merge the github
> changes to the Apache repos - so there is zero issue of IP here.
>
> Whats important is folks can contribute quickly and easily with
> minimum delay or red tape. We're all busy; if you have to wait 2-3
> weeks before you can add a line of text to a document; you're gonna
> find something else to do quite frankly. Waiting weeks for an ICLA
> does not make it easy for newbies to contribute. With github they can
> make their contributions immediately; folks can immediately see it and
> comment on it. Then in parallel work can commence on getting the ICLA
> in place so the changes can be merged to Apache. Indeed while the ICLA
> is being processed the user can make more contributions. When the ICLA
> is done then a committer can merge in whatever documentation changes
> they've made.
Over the last 5 years, I've rarely seen people contributing a lot to
the doc without being or becoming committers.
I don't want to change a technical decision based on the fact that
people *might* need something, but rather what people actually need.
You are a committer, so you can access / modify the documentation
without any problems. So what are your real problems with the current
solution ? We can easily set up nightly uploads or even an hourly
cron job (though given the change rate, i think a nightly one should
be sufficient). If you need an editor, you always find some software
I think such as
http://www.labnol.org/software/wysiwyg-wiki-editor/18062/ though I
tend to use the "mvn jetty:run" which works quite well as you can see
your changes immediately.
The main problem is that we've been asked by infra to get rid of
confluence, so I certainly don't want to think about getting back to
confluence unless infra retracts.
>
> --
> James
> -------
> FuseSource
> Email: james@fusesource.com
> Web: http://fusesource.com
> Twitter: jstrachan, fusenews
> Blog: http://macstrac.blogspot.com/
>
> Open Source Integration and Messaging
>
--
------------------------
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com
Re: Karaf first birthday concall minute notes
Posted by James Strachan <ja...@fusesource.com>.
On 17 June 2011 11:16, Christian Schneider <ch...@die-schneider.net> wrote:
> Hi James,
>
> first thanks for your explanations.
>
> Am 17.06.2011 11:14, schrieb James Strachan:
>>
>> On 17 June 2011 09:19, Christian Schneider<ch...@die-schneider.net>
>> wrote:
>>>
>>> I know that I have proposed this before and then got the answer that this
>>> was discussed already. Still I have the feeling that everybody dislikes
>>> the
>>> current way we build our website.... so again a try :-)...
>>
>> I'm not sure you realise how much dislike there is for wikis?
>>
> I did not realize but I am starting to see :-) I only saw the
>>
>> Wikis don't help committers and don't help users (as you end up with
>> crap everywhere from different versions - or worse documentation for
>> stuff thats not even released yet); all just in case we hope one day
>> someone will turn up and dump a load of useful stuff in the wiki (that
>> never really happens).
>
> That is true help from people outside the project is rare.
>>
>> Incidentally I'm even finding the argument that a wiki is the easiest
>> way to get contributions to have less and less value these days since
>> github. Its actually easier for a total newbie to come along, fork an
>> apache project's git repo on github.com, edit some text files& do a
>> pull request than it is to pester folks for write access to the wiki
>> first before they can even begin to contribute anything. The wiki has
>> a much larger barrier to entry than github.
>
> Github would be a great way to improve the documentation workflow for karaf.
> You would not
> need to open a jira issue to make a change and apply patch. Sadly we are
> stuck with subversion.
Sure - the sooner we can ditch subversion at Apache the better.
However still the easiest way to get new documentation contributions
today at Apache is to get folks to fork the apache repos at github.
Then asynchronously do the ICLA stuff; not block on the ICLA first.
>> Imagine for a second, you are a newbie - you've seen some issue or
>> have an idea for a little page; with github 2 clicks, 20 seconds later
>> you're editing the file in question or writing the new file then
>> firing off the pull request and getting on with your life doing
>> something else. With a wiki you try editing; doesn't work, so you
>> shoot off an email for access then wait. Then after a random time
>> period of hours to days you get more mails then at some point later,
>> you get the ability to login again to the wiki and hopefully you can
>> now edit the page. By the time you get access you've probably
>> forgotten what you were gonna do in the first place :)
>
> The process of getting rights for the wiki is a problem of course. But it is
> necesary as we need the icla to accept contributions.
> That may also be a big problem with github. You send a pull request but that
> opens a big problem with IP issues. I think a pull request
> does not include that the user declares that he has the rights on the code
> he submits and may donate them to apache. In fact it does not even say he
> donates the code at all.
> So for example offering dual licenses later is a problem. I think this is a
> big issue with github. I am not sure how important this is for documentation
> though.
We need the ICLA before we can merge into our repo. However thats a
completely separate issue to the potential new contributor being able
to actually create their contribution in the first place. The ICLA
stuff can be done in parallel after their initial contribution and it
really doesn't matter if it takes weeks to do (which it usually does
anyway). Apache committers are the only ones who merge the github
changes to the Apache repos - so there is zero issue of IP here.
Whats important is folks can contribute quickly and easily with
minimum delay or red tape. We're all busy; if you have to wait 2-3
weeks before you can add a line of text to a document; you're gonna
find something else to do quite frankly. Waiting weeks for an ICLA
does not make it easy for newbies to contribute. With github they can
make their contributions immediately; folks can immediately see it and
comment on it. Then in parallel work can commence on getting the ICLA
in place so the changes can be merged to Apache. Indeed while the ICLA
is being processed the user can make more contributions. When the ICLA
is done then a committer can merge in whatever documentation changes
they've made.
--
James
-------
FuseSource
Email: james@fusesource.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration and Messaging
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi James,
first thanks for your explanations.
Am 17.06.2011 11:14, schrieb James Strachan:
> On 17 June 2011 09:19, Christian Schneider<ch...@die-schneider.net> wrote:
>> I know that I have proposed this before and then got the answer that this
>> was discussed already. Still I have the feeling that everybody dislikes the
>> current way we build our website.... so again a try :-)...
> I'm not sure you realise how much dislike there is for wikis?
>
I did not realize but I am starting to see :-) I only saw the
>
> Wikis don't help committers and don't help users (as you end up with
> crap everywhere from different versions - or worse documentation for
> stuff thats not even released yet); all just in case we hope one day
> someone will turn up and dump a load of useful stuff in the wiki (that
> never really happens).
That is true help from people outside the project is rare.
>
> Incidentally I'm even finding the argument that a wiki is the easiest
> way to get contributions to have less and less value these days since
> github. Its actually easier for a total newbie to come along, fork an
> apache project's git repo on github.com, edit some text files& do a
> pull request than it is to pester folks for write access to the wiki
> first before they can even begin to contribute anything. The wiki has
> a much larger barrier to entry than github.
Github would be a great way to improve the documentation workflow for
karaf. You would not
need to open a jira issue to make a change and apply patch. Sadly we are
stuck with subversion.
> Imagine for a second, you are a newbie - you've seen some issue or
> have an idea for a little page; with github 2 clicks, 20 seconds later
> you're editing the file in question or writing the new file then
> firing off the pull request and getting on with your life doing
> something else. With a wiki you try editing; doesn't work, so you
> shoot off an email for access then wait. Then after a random time
> period of hours to days you get more mails then at some point later,
> you get the ability to login again to the wiki and hopefully you can
> now edit the page. By the time you get access you've probably
> forgotten what you were gonna do in the first place :)
The process of getting rights for the wiki is a problem of course. But
it is necesary as we need the icla to accept contributions.
That may also be a big problem with github. You send a pull request but
that opens a big problem with IP issues. I think a pull request
does not include that the user declares that he has the rights on the
code he submits and may donate them to apache. In fact it does not even
say he donates the code at all.
So for example offering dual licenses later is a problem. I think this
is a big issue with github. I am not sure how important this is for
documentation though.
Christian
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by James Strachan <ja...@fusesource.com>.
On 17 June 2011 09:19, Christian Schneider <ch...@die-schneider.net> wrote:
> I know that I have proposed this before and then got the answer that this
> was discussed already. Still I have the feeling that everybody dislikes the
> current way we build our website.... so again a try :-)...
I'm not sure you realise how much dislike there is for wikis?
> I would even go a step farther and do as much of the website on the wiki as
> possible. Dan Kulp has written an exporter script that syncs the wiki to
> static pages so the admins can live with it.
I've now worked on many OSS projects over the years and I can honestly
say wikis are a huge PITA for managing open source documentation &
websites. Its a great example of theory not matching practice.
IMHO the wiki should be for user submitted content which then gets
merged into source control and versioned & branched. You rarely ever
get much user submitted content anyway; most of the hard work is done
by the committers; who generally prefer to use things like, source
control, branching, merging, a text editor or an IDE! To be able to do
things like, grep, search & replace. Or wacky things like hack
documentation when on a plane. Commit documentation *with* code
changes so they are always in sync; so you can be documenting
experimental features in trunk or merging docs from production
releases to trunk etc.
So use a wiki for arbitrary user submitted content (you're still open
to any contribution from non committers); then let committers use the
best tools they have - source control & powerful editors to merge
contributions into versioned releases & versioned documentation sites;
so user get the documentation which actually matches their exact
version & pages are not littered with "if you are on version X then...
else if version Y then...." like the Camel pages are for example.
Wikis don't help committers and don't help users (as you end up with
crap everywhere from different versions - or worse documentation for
stuff thats not even released yet); all just in case we hope one day
someone will turn up and dump a load of useful stuff in the wiki (that
never really happens).
Incidentally I'm even finding the argument that a wiki is the easiest
way to get contributions to have less and less value these days since
github. Its actually easier for a total newbie to come along, fork an
apache project's git repo on github.com, edit some text files & do a
pull request than it is to pester folks for write access to the wiki
first before they can even begin to contribute anything. The wiki has
a much larger barrier to entry than github.
Imagine for a second, you are a newbie - you've seen some issue or
have an idea for a little page; with github 2 clicks, 20 seconds later
you're editing the file in question or writing the new file then
firing off the pull request and getting on with your life doing
something else. With a wiki you try editing; doesn't work, so you
shoot off an email for access then wait. Then after a random time
period of hours to days you get more mails then at some point later,
you get the ability to login again to the wiki and hopefully you can
now edit the page. By the time you get access you've probably
forgotten what you were gonna do in the first place :)
So I'm tempted to suggest, to simplify things - just scrap the wiki
entirely. If you had the choice of submitting content to a source
control system or a wiki; I suspect plenty of contributors would go
for the github route as its easier & lets folks get started
contributing immediately with the best tools available without waiting
for some humans to read emails and do stuff; there's no pestering
people to get access just to be able to write some text files in a web
browser (which isn't ideal anyway).
Though that might be a little to radical for some who still like the
concept of a wiki despite its huge practical flaws, so how about we
say, use source control for the main documentation & site then have a
wiki as the 'wishing well' so we can hope that one day some
non-committers come along and chuck useful stuff in there. If they do,
great, we can merge it into source control for the relevant release
they're talking about. If not, its just another thing for infra to
maintain.
--
James
-------
FuseSource
Email: james@fusesource.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration and Messaging
Re: Karaf first birthday concall minute notes
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Hi Christian,
I have no problem to discuss about that and submit to a vote.
First, a quick history about that :)
On both Karaf and ServiceMix, we had (and still have) documentation
requirements with a multi-format outputs (PDF, HTML) and professional
look'n feel.
Another requirement is to be able to "link" the documentation with a
specific Karaf version. The documentation could be widely different
between Karaf 2.1.x and Karaf 3.0.x for instance.
Starting with these requirements, we discussed around:
1/ usage of the Apache confluence wiki to store the documentation and
use of an "external" tool (such as Prince) to extract content from the
wiki and generate the document output (PDF). It looks like the way it
does in Camel.
2/ usage of DocBook directly into the Karaf svn repo
3/ usage of Scalate directly into the Karaf svn repo
Here's the conclusions that we had regarding the previous points:
1/ it seems that the Apache confluence wiki future is not really clear.
There were discussion around Apache CMS, cwiki EOL, etc.
If we "invest" a lot in the documentation on the wiki, it could "cost" a
lot very soon depending of the cwiki future. That's why we voted to not
use directly cwiki.
2/ DocBook is XML document, very rich namespace but no always easy (I
don't say that as I love DocBook but it's the feedback that we got ;)).
3/ Scalate documentation was the choice because the syntax is really
close to wiki and the mechanism is like DocBook document generation. So
it's like a solution in the middle.
To be honest, I was more on 2/ or 3/ at the beginning. But, when I see
the Camel documentation and website, I'm quite around to revert my point
of view ;). It's clear that Karaf (and ServiceMix, that's why I added
ServiceMix dev mailing list in copy of this e-mail) documentation and
website could be managed in the same way that Camel does.
My only concern is that we decide to move back to cwiki (I don't mind to
make the effort, I will do it), we need to have a clear view about the
cwiki future and relationship with Apache CMS.
I'm sure that the ASF members could provide us more information:
@gnodet, @dkulp ?
Regards
JB
On 06/17/2011 10:19 AM, Christian Schneider wrote:
> I know that I have proposed this before and then got the answer that
> this was discussed already. Still I have the feeling that everybody
> dislikes the current way we build our website.... so again a try :-)...
>
> I would even go a step farther and do as much of the website on the wiki
> as possible. Dan Kulp has written an exporter script that syncs the wiki
> to static pages so the admins can live with it.
>
> I think we have to try to make the website and documentation as open as
> possible. The wiki allows us to give editing right to anyone with a
> valid icla. That is much more accessible than the current site.
> Additionally any change can be seen right after the change on the wiki.
> I think that is a big motivation. Currently you have to submit a patch
> for the website and wait for someone to commit it and then for someeone
> else to sync it to the web. This process can take months sometimes. That
> is quite frustrating and I am sure it is the reason why we have so few
> updates to the site and documentation.
> Another nice thing of the wiki is that it is a first step of
> contribution below submitting patches. So people can come in contact
> with the project gradually.
>
> Of course the wiki has the problem that it is not synched to the
> releases but in cxf and camel this is also not the case. Still it works
> well there. The way to couple the documentation to releases is to note
> for example which attribute of a command has been introduced in which
> version. This is niot perfect but works quite well in practice.
>
> Christian
>
>
> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>> Agree Andreas,
>>
>> I think that:
>> - link to the wiki "cap" page in the community area of the website
>> - wiki pages as children of the "cap" page
>>
>> is the most efficient way.
>>
>> Regards
>> JB
>
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi James,
Am 17.06.2011 11:24, schrieb James Strachan:
>
> Using a text area in a web browser is more accessible than editing a
> file on a file system? Or do you imagine folks are gonna come along
> who totally grok complex technology like OSGi containers or ESB stuff;
> but who can't grasp source control and editing files?
The problem is not the text editor. It is the number of steps needed to
edit the documentation. Especially as a non committer it is quite
frustrating.
Please seem my answer to guillaume´s mail. There I described how many
steps and people you need to do a small change on the documentation.
>> The other thing is that while it may seem the documentation is linked to a
>> certain version this is not true in practice. For example it is quite common
>> to
>> release a functionality and refine the documentation for it later.
> You can do that too; you can have documentation branches and merge
> things from code<-> doc branches as and when required. Have a
> 'current website' branch and choose what gets updated when.
This sounds nice in theory and I also voted to do documentation this way
in a project at my former employer. The problem was that the
documentation that flourished nicely in the wiki started to starve when
we changed to subversion. Only developers were making changes the user
did not a single change.
While they participated nicely in the wiki.
In the end we found that most people are interested in the most current
documentation. Sometimes it will not reflect their perhaps old version
of the software anymore
but at least they know it is the most current one and all the experience
from for example mailing list discussions went into it.
>> The third thing is that the confluence wiki is the only solution I know that
>> has a decent support for creating grahpics for the documentation (gliffy
>> http://www.gliffy.com/).
> Oh please. Seriously? jpg, gif, visio, omnigraffle, graphviz... You
> can't think of any way of making some graphics and checking them into
> source code?
The problem is not with checking them into the code. The problem is the
whole workflow. You have to edit the file with your grahpical tool, save
it, call some conversion
process to make it viewable on the web. Then this conversion process has
to be created at first. You also have to install the grahpical tool
first. There is no readily available solution.
In confluence you click on the diagram. Gliffy opens and when you save,
it is visible to everyone. That is a completely different experience.
Christian
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by James Strachan <ja...@fusesource.com>.
On 17 June 2011 09:58, Christian Schneider <ch...@die-schneider.net> wrote:
> Hi Achim,
>
> in theory I like creating documentation from the same source as the code.
> The ability to version it together sounds appealing.
>
> The problem is that some things are different to code:
>
> People who write documentation are often different from developers. So they
> often prefer more accessible tools.
Using a text area in a web browser is more accessible than editing a
file on a file system? Or do you imagine folks are gonna come along
who totally grok complex technology like OSGi containers or ESB stuff;
but who can't grasp source control and editing files?
> The other thing is that while it may seem the documentation is linked to a
> certain version this is not true in practice. For example it is quite common
> to
> release a functionality and refine the documentation for it later.
You can do that too; you can have documentation branches and merge
things from code <-> doc branches as and when required. Have a
'current website' branch and choose what gets updated when.
> The third thing is that the confluence wiki is the only solution I know that
> has a decent support for creating grahpics for the documentation (gliffy
> http://www.gliffy.com/).
Oh please. Seriously? jpg, gif, visio, omnigraffle, graphviz... You
can't think of any way of making some graphics and checking them into
source code?
> Those graphics can really improve documentation.
Sure, graphics rock. Not liking wikis for opens source project
documentation doesn't mean you don't like pictures.
> With text files in subversion I do not know any simple way to achieve the
> same.
I heard they figured out how to store binary files too in source
control. Did you know you can check them in if you want to?
--
James
-------
FuseSource
Email: james@fusesource.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration and Messaging
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
Hi Achim,
in theory I like creating documentation from the same source as the
code. The ability to version it together sounds appealing.
The problem is that some things are different to code:
People who write documentation are often different from developers. So
they often prefer more accessible tools.
The other thing is that while it may seem the documentation is linked to
a certain version this is not true in practice. For example it is quite
common to
release a functionality and refine the documentation for it later. So
while you do not want the code to change after it is released you often
want the documentation to
change.
The third thing is that the confluence wiki is the only solution I know
that has a decent support for creating grahpics for the documentation
(gliffy http://www.gliffy.com/). Those graphics can really improve
documentation. With text files in subversion I do not know any simple
way to achieve the same.
I am not even too sure about the requirement for sveral outputs. I think
almost all users of camel and cxf use the web instead of the pdf
version. So I am not sure how much value this other format has.
Christian
Am 17.06.2011 10:37, schrieb Achim Nierbeck:
> Hi Christian,
>
> nice Try :-)
>
> actually I like the way the page works right now, it's just something
> that needs a bit more "tweaking".
>
> I'd rather see the current process enhance a bit. The generation of
> HTML and PDF out of the documentation
> in code, I rather like. This way the documentation is "closer" to the code.
>
> It's just that certain pages which are more dynamic than the manual
> could be written in Confluence and
> be "subpaged"
>
> another thing I would like to see is a "trunk based" documentation to
> show the current documentation
> this way People are closer to the current development.
>
> Regards, Achim
>
--
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
Talend Application Integration Division http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by Achim Nierbeck <bc...@googlemail.com>.
Hi Christian,
nice Try :-)
actually I like the way the page works right now, it's just something
that needs a bit more "tweaking".
I'd rather see the current process enhance a bit. The generation of
HTML and PDF out of the documentation
in code, I rather like. This way the documentation is "closer" to the code.
It's just that certain pages which are more dynamic than the manual
could be written in Confluence and
be "subpaged"
another thing I would like to see is a "trunk based" documentation to
show the current documentation
this way People are closer to the current development.
Regards, Achim
2011/6/17 Christian Schneider <ch...@die-schneider.net>:
> I know that I have proposed this before and then got the answer that this
> was discussed already. Still I have the feeling that everybody dislikes the
> current way we build our website.... so again a try :-)...
>
> I would even go a step farther and do as much of the website on the wiki as
> possible. Dan Kulp has written an exporter script that syncs the wiki to
> static pages so the admins can live with it.
>
> I think we have to try to make the website and documentation as open as
> possible. The wiki allows us to give editing right to anyone with a valid
> icla. That is much more accessible than the current site.
> Additionally any change can be seen right after the change on the wiki. I
> think that is a big motivation. Currently you have to submit a patch for the
> website and wait for someone to commit it and then for someeone else to sync
> it to the web. This process can take months sometimes. That is quite
> frustrating and I am sure it is the reason why we have so few updates to the
> site and documentation.
> Another nice thing of the wiki is that it is a first step of contribution
> below submitting patches. So people can come in contact with the project
> gradually.
>
> Of course the wiki has the problem that it is not synched to the releases
> but in cxf and camel this is also not the case. Still it works well there.
> The way to couple the documentation to releases is to note for example which
> attribute of a command has been introduced in which version. This is niot
> perfect but works quite well in practice.
>
> Christian
>
>
> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>>
>> Agree Andreas,
>>
>> I think that:
>> - link to the wiki "cap" page in the community area of the website
>> - wiki pages as children of the "cap" page
>>
>> is the most efficient way.
>>
>> Regards
>> JB
>
> --
> Christian Schneider
> http://www.liquid-reality.de
>
> Open Source Architect
> http://www.talend.com
>
>
--
--
*Achim Nierbeck*
Apache Karaf <http://karaf.apache.org/> Committer & PMC
OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/>
Committer & Project Lead
Re: Karaf first birthday concall minute notes
Posted by James Strachan <ja...@fusesource.com>.
On 17 June 2011 09:19, Christian Schneider <ch...@die-schneider.net> wrote:
> I know that I have proposed this before and then got the answer that this
> was discussed already. Still I have the feeling that everybody dislikes the
> current way we build our website.... so again a try :-)...
I'm not sure you realise how much dislike there is for wikis?
> I would even go a step farther and do as much of the website on the wiki as
> possible. Dan Kulp has written an exporter script that syncs the wiki to
> static pages so the admins can live with it.
I've now worked on many OSS projects over the years and I can honestly
say wikis are a huge PITA for managing open source documentation &
websites. Its a great example of theory not matching practice.
IMHO the wiki should be for user submitted content which then gets
merged into source control and versioned & branched. You rarely ever
get much user submitted content anyway; most of the hard work is done
by the committers; who generally prefer to use things like, source
control, branching, merging, a text editor or an IDE! To be able to do
things like, grep, search & replace. Or wacky things like hack
documentation when on a plane. Commit documentation *with* code
changes so they are always in sync; so you can be documenting
experimental features in trunk or merging docs from production
releases to trunk etc.
So use a wiki for arbitrary user submitted content (you're still open
to any contribution from non committers); then let committers use the
best tools they have - source control & powerful editors to merge
contributions into versioned releases & versioned documentation sites;
so user get the documentation which actually matches their exact
version & pages are not littered with "if you are on version X then...
else if version Y then...." like the Camel pages are for example.
Wikis don't help committers and don't help users (as you end up with
crap everywhere from different versions - or worse documentation for
stuff thats not even released yet); all just in case we hope one day
someone will turn up and dump a load of useful stuff in the wiki (that
never really happens).
Incidentally I'm even finding the argument that a wiki is the easiest
way to get contributions to have less and less value these days since
github. Its actually easier for a total newbie to come along, fork an
apache project's git repo on github.com, edit some text files & do a
pull request than it is to pester folks for write access to the wiki
first before they can even begin to contribute anything. The wiki has
a much larger barrier to entry than github.
Imagine for a second, you are a newbie - you've seen some issue or
have an idea for a little page; with github 2 clicks, 20 seconds later
you're editing the file in question or writing the new file then
firing off the pull request and getting on with your life doing
something else. With a wiki you try editing; doesn't work, so you
shoot off an email for access then wait. Then after a random time
period of hours to days you get more mails then at some point later,
you get the ability to login again to the wiki and hopefully you can
now edit the page. By the time you get access you've probably
forgotten what you were gonna do in the first place :)
So I'm tempted to suggest, to simplify things - just scrap the wiki
entirely. If you had the choice of submitting content to a source
control system or a wiki; I suspect plenty of contributors would go
for the github route as its easier & lets folks get started
contributing immediately with the best tools available without waiting
for some humans to read emails and do stuff; there's no pestering
people to get access just to be able to write some text files in a web
browser (which isn't ideal anyway).
Though that might be a little to radical for some who still like the
concept of a wiki despite its huge practical flaws, so how about we
say, use source control for the main documentation & site then have a
wiki as the 'wishing well' so we can hope that one day some
non-committers come along and chuck useful stuff in there. If they do,
great, we can merge it into source control for the relevant release
they're talking about. If not, its just another thing for infra to
maintain.
--
James
-------
FuseSource
Email: james@fusesource.com
Web: http://fusesource.com
Twitter: jstrachan, fusenews
Blog: http://macstrac.blogspot.com/
Open Source Integration and Messaging
Re: Karaf first birthday concall minute notes
Posted by Christian Schneider <ch...@die-schneider.net>.
I know that I have proposed this before and then got the answer that
this was discussed already. Still I have the feeling that everybody
dislikes the current way we build our website.... so again a try :-)...
I would even go a step farther and do as much of the website on the wiki
as possible. Dan Kulp has written an exporter script that syncs the wiki
to static pages so the admins can live with it.
I think we have to try to make the website and documentation as open as
possible. The wiki allows us to give editing right to anyone with a
valid icla. That is much more accessible than the current site.
Additionally any change can be seen right after the change on the wiki.
I think that is a big motivation. Currently you have to submit a patch
for the website and wait for someone to commit it and then for someeone
else to sync it to the web. This process can take months sometimes. That
is quite frustrating and I am sure it is the reason why we have so few
updates to the site and documentation.
Another nice thing of the wiki is that it is a first step of
contribution below submitting patches. So people can come in contact
with the project gradually.
Of course the wiki has the problem that it is not synched to the
releases but in cxf and camel this is also not the case. Still it works
well there. The way to couple the documentation to releases is to note
for example which attribute of a command has been introduced in which
version. This is niot perfect but works quite well in practice.
Christian
Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
> Agree Andreas,
>
> I think that:
> - link to the wiki "cap" page in the community area of the website
> - wiki pages as children of the "cap" page
>
> is the most efficient way.
>
> Regards
> JB
--
Christian Schneider
http://www.liquid-reality.de
Open Source Architect
http://www.talend.com
Re: Karaf first birthday concall minute notes
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Agree Andreas,
I think that:
- link to the wiki "cap" page in the community area of the website
- wiki pages as children of the "cap" page
is the most efficient way.
Regards
JB
On 06/17/2011 09:42 AM, Andreas Pieber wrote:
> Hey,
>
> On Fri, Jun 17, 2011 at 9:18 AM, Jean-Baptiste Onofré<jb...@nanthrax.net> wrote:
>> Following our yesterday concall, I wrote down the minute notes:
>>
>> https://cwiki.apache.org/confluence/display/KARAF/Apache+Karaf+First+Birthday+Meeting+%282011-06-16%29
>
> This looks great; It gives a very good overview of the topics we've
> discussed yesterday.
>
>> As I said yesterday, I will start to work on the Karaf roadmap page and
>> Karaf architecture/implementation draft.
>>
>> I think that these pages should be easily visible by the website visitor.
>> That's why I propose to write it into the Karaf website and not the wiki.
>
> Well the problem with the homepage is still the contribution. Maybe we
> could go somewhere in between and provide only the "headlines" on the
> homepage and link to the wiki page?
>
> Kind regards,
> Andreas
>
> p.s.: thanks for the "birthday party" yesterday! Was cool to get the
> names backed up with voices :)
Re: Karaf first birthday concall minute notes
Posted by Andreas Pieber <an...@gmail.com>.
Hey,
On Fri, Jun 17, 2011 at 9:18 AM, Jean-Baptiste Onofré <jb...@nanthrax.net> wrote:
> Following our yesterday concall, I wrote down the minute notes:
>
> https://cwiki.apache.org/confluence/display/KARAF/Apache+Karaf+First+Birthday+Meeting+%282011-06-16%29
This looks great; It gives a very good overview of the topics we've
discussed yesterday.
> As I said yesterday, I will start to work on the Karaf roadmap page and
> Karaf architecture/implementation draft.
>
> I think that these pages should be easily visible by the website visitor.
> That's why I propose to write it into the Karaf website and not the wiki.
Well the problem with the homepage is still the contribution. Maybe we
could go somewhere in between and provide only the "headlines" on the
homepage and link to the wiki page?
Kind regards,
Andreas
p.s.: thanks for the "birthday party" yesterday! Was cool to get the
names backed up with voices :)