incubator-wave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ali Lown <...@lown.me.uk>
Subject Re: Proposal - Documentation storage
Date Sat, 16 May 2015 22:39:22 GMT
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
View raw message