Hi all, I have sent in a pull request with some minor changes following updating the help information. https://github.com/apache/incubator-wave-docs/pull/2
Can someone review it, so I can commit? Is github sending notification emails here in the same way review board does when a PR is made? If not, should get infra to hook this up. Thanks, Ali On 16 May 2015 at 00:03, Ali Lown <a...@lown.me.uk> wrote: > @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 >>> >>> >> >> > >> >> >> >>> >>> >> >> > >> >> >> >>> >>> >> >> > >> >> >>> >>> >> >> > >> >>> >>> >> >> > >>> >>> >> >> >>> >>> >> >>> >> >>> >> >>> > >>>
