Sounds good to me. On Sun, May 17, 2015 at 1:40 AM Ali Lown <a...@lown.me.uk> wrote:
> 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 > >> >> >>> >> >> > >> >> >> > >> >> >>> >> >> > >> >> >> > >> >> >>> >> >> > >> >> > >> >> >>> >> >> > >> > >> >> >>> >> >> > > >> >> >>> >> >> > >> >> >>> >> > >> >> >> > >> >> >> > >> >> > > >> >> > >> >
