incubator-wave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Yuri Z <vega...@gmail.com>
Subject Re: Proposal - Documentation storage
Date Sun, 17 May 2015 07:24:11 GMT
Sounds good to me.

On Sun, May 17, 2015 at 1:40 AM Ali Lown <ali@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 <vega113@gmail.com> wrote:
> > I think it is.
> >
> > On Sat, May 16, 2015 at 2:03 AM Ali Lown <ali@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 <ehugh1@gmail.com> wrote:
> >> > @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