incubator-wave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Evan Hughes <ehu...@gmail.com>
Subject Re: Proposal - Documentation storage
Date Fri, 15 May 2015 08:06:10 GMT
@Ali, submitted today

On 15 May 2015 at 05:12, Ali Lown <ali@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 <ehugh1@gmail.com> wrote:
> > For Pull request
> >
> > On 9 May 2015 at 17:12, Evan Hughes <ehugh1@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 <ali@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 <ehugh1@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 <ali@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 <ehugh1@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" <pablojan@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 <ali@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 <vega113@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 <ali@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 <ehugh1@gmail.com>
> >>> >> >> > >> wrote:
> >>> >> >> > >> > indeed and yea without a doubt
> >>> >> >> > >> >
> >>> >> >> > >> > On 25 April 2015 at 09:59, Ali Lown
<ali@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 <ehugh1@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 <
> ehugh1@gmail.com>
> >>> >> wrote:
> >>> >> >> > >> >> >
> >>> >> >> > >> >> >> This is a proposal for
....
> >>> >> >> > >> >> >>
> >>> >> >> > >> >> >>
> >>> >> >> > >> >> >> TL;DR
> >>> >> >> > >> >> >>
> >>> >> >> > >> >> >>
> >>> >> >> > >> >>
> >>> >> >> > >>
> >>> >> >> >
> >>> >> >>
> >>> >>
> >>
> >>
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message