Okay. I merged and pushed those changes. Should I be squashing the commits into a single one before pushing? Does anyone have any preferences on this/other parts of git - branching and tagging documentation?
I was assuming we have something along the lines of a branch of docs for each major release version, and we could potentially tag documentation to match final releases including minor versions? Ali On 16 May 2015 at 11:49, Yuri Z <vega...@gmail.com> wrote: > I think it is. > > On Sat, May 16, 2015 at 2:03 AM 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 >> >> >>> >> >> > >> >> >> >> >> >>> >> >> > >> >> >> >> >> >>> >> >> > >> >> >> >> >>> >> >> > >> >> >> >>> >> >> > >> >> >>> >> >> >> >> >>> >> >> >> >> >> >> >> >> >> > >> >> >>
