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: ja...@fusesource.com Web: http://fusesource.com Twitter: jstrachan, fusenews Blog: http://macstrac.blogspot.com/ Open Source Integration and Messaging
