@Evan: Okay great. I have merged this PR into the incubator-wave-docs repo.
For reference: as the github repo is a mirror, with the master being on git-wip-us.apache.org, I merged the PR by adding a new remote to my local repository which was Evan's repository, then merging the relevant commits locally and pushing it back upstream. Github can auto-detect this occurred and closed the PR for me. Does this seem a reasonable workflow? Ali On 15 May 2015 at 09:06, Evan Hughes <ehu...@gmail.com> wrote: > @Ali, submitted today > > On 15 May 2015 at 05:12, Ali Lown <a...@lown.me.uk> wrote: > >> @Evan: That PR looks fine to me. >> One thing: Have you submitted an ICLA to Apache? It seems like it >> would be a good idea to do at some point, as you are likely to >> continue making not-insignificant changes to this repo. >> >> @Yuri/Others: How do we want to handle PR reviews? >> I propose doing it the same way as on review-board, of leaving >> comments on the system as appropriate. >> Do we want to wait for multiple committers to say LGTM? >> >> I propose that at the moment, whilst the documentation repo is being >> built up, that we just commit the PRs after looking over them for >> sanity, and then lock it down a bit once stabilized to the current >> code base? >> >> To avoid stalling this progress any longer, I will commit Evans PR >> within the next 24hrs unless someone says otherwise. >> >> Ali >> >> On 9 May 2015 at 13:55, Evan Hughes <ehu...@gmail.com> wrote: >> > For Pull request >> > >> > On 9 May 2015 at 17:12, Evan Hughes <ehu...@gmail.com> wrote: >> >> >> >> I believe we should split the docs into: >> >> >> >> Documentation => Documents how to build the documentation and how to >> use >> >> sphinx + ReST (mostly just an example and to help ease the transition) >> >> manual => The user manual provided with the client (How to >> >> make a wave, .....) >> >> developer => Everything a developer would need, how to start >> the >> >> server, how to build, how to contribute >> >> api => How to build with the gadgets/robot api >> >> protocol => All about the protocol specifications >> >> >> >> after the "Documentation" is built I will submit a pull request to the >> >> main so you guys can see if you like it. >> >> >> >> On 6 May 2015 at 00:41, Ali Lown <a...@lown.me.uk> wrote: >> >>> >> >>> The repository is at https://github.com/apache/incubator-wave-docs, >> >>> and is rather empty at the moment. >> >>> I see no reason we shouldn't accept pull requests to this repo, so I >> >>> suggest you use that workflow... >> >>> >> >>> Sphinx sounds fine. Many people will be familiar with rest (it shares >> >>> a lot with markdown but is more powerful) thanks to Python docs making >> >>> use of it. >> >>> >> >>> Can we find any other volunteers for moving the docs out of >> >>> confluence, as there is quite a lot to do....? >> >>> >> >>> Ali >> >>> >> >>> On 1 May 2015 at 04:03, Evan Hughes <ehu...@gmail.com> wrote: >> >>> > I think sphinx would be a better option than jekyll for the >> >>> > documentation, >> >>> > it does use restructured text instead of markdown but is more >> >>> > extensible >> >>> > and can easily produce a pdf format compared to markdown. Gonna spin >> up >> >>> > my >> >>> > own repo and see how it is, been looking at the syntax and it isn't >> >>> > that >> >>> > bad. >> >>> > >> >>> > On 1 May 2015 at 01:53, Ali Lown <a...@lown.me.uk> wrote: >> >>> > >> >>> >> Okay. A new repository has been made: >> >>> >> https://git-wip-us.apache.org/repos/asf?p=incubator-wave-docs.git >> >>> >> >> >>> >> I have requested github integration for it, so we can use pull >> >>> >> requests if we would like to... >> >>> >> >> >>> >> Ali >> >>> >> >> >>> >> On 29 April 2015 at 00:53, Evan Hughes <ehu...@gmail.com> wrote: >> >>> >> > I like the idea of also moving the website off of the cms but not >> >>> >> > sure if >> >>> >> > it should be in same repository. Ill look into jekyll for the >> >>> >> documentation >> >>> >> > but theres also other build systems which might be better for us >> aka >> >>> >> > html >> >>> >> > and pdf export. >> >>> >> > >> >>> >> > Go ahead with the repository for the documentation and well go >> from >> >>> >> there. >> >>> >> > Well need to transfer any issues in jira or deal with them during >> >>> >> > the >> >>> >> > transition >> >>> >> > On 29/04/2015 1:20 AM, "Pablo Ojanguren" <pablo...@gmail.com> >> >>> >> > wrote: >> >>> >> > >> >>> >> >> +1 Moving doc to git would be good, moreover if we update and >> >>> >> >> improve >> >>> >> it a >> >>> >> >> litlle bit along the migration process (at least the >> organization). >> >>> >> >> >> >>> >> >> 2015-04-28 16:40 GMT+02:00 Ali Lown <a...@lown.me.uk>: >> >>> >> >> >> >>> >> >> > Yuri, >> >>> >> >> > >> >>> >> >> > I think the main reason to move is to make it easier for people >> >>> >> >> > to >> >>> >> >> > make changes, over the existing confluence system. So I would >> >>> >> >> > have >> >>> >> >> > though that improving the documentation is something people >> would >> >>> >> >> > be >> >>> >> >> > more likely to do afterwards. >> >>> >> >> > >> >>> >> >> > I agree that opening some tickets where the documentation could >> >>> >> >> > be >> >>> >> >> > improved does help highlight the problem, but it doesn't make >> it >> >>> >> >> > any >> >>> >> >> > easier for people to fix. >> >>> >> >> > >> >>> >> >> > Ali >> >>> >> >> > >> >>> >> >> > P.s. Do you want me to do anything for RC9, or are you happy to >> >>> >> >> > submit >> >>> >> >> > one? Are you waiting on me for anything still? >> >>> >> >> > >> >>> >> >> > On 28 April 2015 at 15:36, Yuri Z <vega...@gmail.com> wrote: >> >>> >> >> > > Maybe it would be better to move in small steps. Like to go >> >>> >> >> > > over >> >>> >> >> current >> >>> >> >> > > documentation and open tickets with requests for improvements >> >>> >> wherever >> >>> >> >> > > something is missing or not clear. >> >>> >> >> > > >> >>> >> >> > > On Tue, Apr 28, 2015 at 5:33 PM Ali Lown <a...@lown.me.uk> >> >>> >> >> > > wrote: >> >>> >> >> > > >> >>> >> >> > >> Well, doesn't look like anybody else has much opinion. >> >>> >> >> > >> >> >>> >> >> > >> Shall I just raise a ticket for a new repo for this? >> >>> >> >> > >> >> >>> >> >> > >> It probably makes sense to put the whole website under it, >> >>> >> >> > >> rather >> >>> >> than >> >>> >> >> > >> using the combination of Apache CMS website + Confluence >> that >> >>> >> >> > >> we do >> >>> >> >> > >> currently. We could just use Jekyll for both website and >> docs? >> >>> >> >> > >> >> >>> >> >> > >> Ali >> >>> >> >> > >> >> >>> >> >> > >> >> >>> >> >> > >> On 25 April 2015 at 02:52, Evan Hughes <ehu...@gmail.com> >> >>> >> >> > >> wrote: >> >>> >> >> > >> > indeed and yea without a doubt >> >>> >> >> > >> > >> >>> >> >> > >> > On 25 April 2015 at 09:59, Ali Lown <a...@lown.me.uk> >> wrote: >> >>> >> >> > >> > >> >>> >> >> > >> >> Hi Evan, >> >>> >> >> > >> >> >> >>> >> >> > >> >> +1 >> >>> >> >> > >> >> >> >>> >> >> > >> >> After giving this some more thought post the Hangout, I >> do >> >>> >> >> > >> >> think >> >>> >> >> that >> >>> >> >> > >> >> moving the docs to Git provides us with a measurable >> >>> >> >> > >> >> improvement >> >>> >> >> over >> >>> >> >> > >> >> the current situation - particularly with the ability to >> >>> >> >> > >> >> keep >> >>> >> docs >> >>> >> >> > >> >> synced with the releases via branches, and the reduced >> >>> >> >> > >> >> barrier >> >>> >> to >> >>> >> >> > >> >> entry for changing them. >> >>> >> >> > >> >> >> >>> >> >> > >> >> Would you be interested in leading the migration effort? >> >>> >> >> > >> >> >> >>> >> >> > >> >> Ali >> >>> >> >> > >> >> >> >>> >> >> > >> >> On 24 April 2015 at 05:59, Evan Hughes <ehu...@gmail.com >> > >> >>> >> wrote: >> >>> >> >> > >> >> > woops, my bad >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > This is a proposal for the storage of documentation to >> be >> >>> >> moved >> >>> >> >> to >> >>> >> >> > a >> >>> >> >> > >> git >> >>> >> >> > >> >> > repository instead of on confluence and leave >> confluence >> >>> >> >> > >> >> > as a >> >>> >> >> place >> >>> >> >> > >> for >> >>> >> >> > >> >> > other technical documents used by developers. >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > *Confluence:* >> >>> >> >> > >> >> > *The issues:* >> >>> >> >> > >> >> > - contributors must ask for permission from the >> >>> >> mailing >> >>> >> >> > list >> >>> >> >> > >> to >> >>> >> >> > >> >> be >> >>> >> >> > >> >> > given the privilege settings to edit/create pages >> >>> >> >> > >> >> > - Simple revision history is kept but is more >> >>> >> difficult >> >>> >> >> to >> >>> >> >> > >> easy >> >>> >> >> > >> >> > transition documentation between wave release versions, >> >>> >> >> > >> >> > more >> >>> >> of a >> >>> >> >> > >> running >> >>> >> >> > >> >> > active document >> >>> >> >> > >> >> > *The good:* >> >>> >> >> > >> >> > * - *easily able to export to pdf and web >> formats >> >>> >> >> > >> >> > - has an easy online rich editor >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > *Git (markdown):* >> >>> >> >> > >> >> > * The issues:* >> >>> >> >> > >> >> > * - *setup as a new repository? a folder in >> >>> >> >> > >> >> > current >> >>> >> >> > repository? >> >>> >> >> > >> >> > apache will need to be involved if a new repository is >> to >> >>> >> >> > >> >> > be >> >>> >> >> setup >> >>> >> >> > >> >> > - exporting the markdown files into a >> meaningful >> >>> >> >> > >> representation >> >>> >> >> > >> >> > (web, pdf), many build systems exist but custom system >> >>> >> >> > >> >> > can >> >>> >> also >> >>> >> >> be >> >>> >> >> > >> >> written >> >>> >> >> > >> >> > by our committers >> >>> >> >> > >> >> > * The good:* >> >>> >> >> > >> >> > * - *less of a roadblock, allows users to >> >>> >> >> > >> >> > contribute >> >>> >> more, >> >>> >> >> > also >> >>> >> >> > >> >> > allows new committers a trial at how to add commits >> using >> >>> >> >> > >> >> > the >> >>> >> >> > apache >> >>> >> >> > >> >> > procedures >> >>> >> >> > >> >> > - Highly customisable >> >>> >> >> > >> >> > - Revision history and versions easily achieved >> >>> >> >> > >> >> > for >> >>> >> >> example >> >>> >> >> > >> with >> >>> >> >> > >> >> > branches (master, 0.4.x, 0.5.x, ....) >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > *TL;DR* >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > Confluence is a rich wiki but can limit the >> availability >> >>> >> >> > >> >> > for >> >>> >> >> > >> committers >> >>> >> >> > >> >> to >> >>> >> >> > >> >> > publish updates (need to ask permission, which isn't >> that >> >>> >> hard) >> >>> >> >> and >> >>> >> >> > >> is a >> >>> >> >> > >> >> > good place to store technical information for the >> >>> >> >> > >> >> > project. >> >>> >> >> > >> >> > A markdown written file structured documentation >> >>> >> implementation >> >>> >> >> is >> >>> >> >> > >> more >> >>> >> >> > >> >> > accessible to developers, follows a more natural flow >> and >> >>> >> >> > >> >> > can >> >>> >> be >> >>> >> >> > >> highly >> >>> >> >> > >> >> > customised and has great revision structure. >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > *Relevant Jira Issues:* >> >>> >> >> > >> >> > * - none* >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > *Please express your opinions below and if enough >> >>> >> >> > >> >> > feedback is >> >>> >> >> > present >> >>> >> >> > >> a >> >>> >> >> > >> >> > vote from the mailing list should be called after the >> >>> >> >> discussion. * >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > >> >>> >> >> > >> >> > On 24 April 2015 at 14:28, Evan Hughes < >> ehu...@gmail.com> >> >>> >> wrote: >> >>> >> >> > >> >> > >> >>> >> >> > >> >> >> This is a proposal for .... >> >>> >> >> > >> >> >> >> >>> >> >> > >> >> >> >> >>> >> >> > >> >> >> TL;DR >> >>> >> >> > >> >> >> >> >>> >> >> > >> >> >> >> >>> >> >> > >> >> >> >>> >> >> > >> >> >>> >> >> > >> >>> >> >> >> >>> >> >> >> >> >> >> > >>
