cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Shazron <shaz...@gmail.com>
Subject Re: Documentation update to previous version
Date Tue, 25 Jun 2013 05:28:19 GMT
Not sure. An idea is one branch per version? So if you work on master, that
is "edge". To grab a whole directory of version docs, write a script that
exports the contents of each branch (git-checkout-index) into a folder with
the same branch name (or mapped), then run joDoc (our current tool)


On Mon, Jun 24, 2013 at 5:23 PM, Carlos Santana <csantana23@gmail.com>wrote:

> Are there plans for a "*for a saner doc system*" ?
>
> --Carlos
>
>
>
> On Mon, Jun 24, 2013 at 7:25 PM, Shazron <shazron@gmail.com> wrote:
>
> > Did a major update for previous versions. It's such a pain if we miss a
> doc
> > update for a version X, and we're at version X+2.
> >
> > At master branch, you update for edge, X+2, X+1 and X folders.
> > At X+2 branch, you update for edge, X+2, X+1 and X folders.
> > At X+1 branch, you update for edge, X+1, and X folders.
> > At X, you update for edge, and X folders.
> >
> > So that is 13 updates of the same doc over 4 branches (which you have to
> > apply deltas too, so you don't knock out any other changes of course).
> > Hoping for a saner doc system...
> >
> >
> > On Wed, Jun 19, 2013 at 9:59 PM, Michael Brooks <
> michael@michaelbrooks.ca
> > >wrote:
> >
> > > Thanks Shaz!
> > >
> > > I was away for JSConf, so another contributor handled the cordova-docs
> > > release for 2.8.0.
> > >
> > > Michael
> > >
> > >
> > > On Wed, Jun 19, 2013 at 1:46 PM, Shazron <shazron@gmail.com> wrote:
> > >
> > > > This commit that was tagged 2.8.0:
> > > >
> > > >
> > >
> >
> https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=commit;h=1d2fdf5a3344a554136c505b162d1931e878daad
> > > >
> > > > Does not occur in branch 2.8.x:
> > > >
> > > >
> > >
> >
> https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=shortlog;h=refs/heads/2.8.x
> > > >
> > > > Nor does the tagged commit occur in master(!) - the commit there has
> a
> > > > different sha1:
> > > >
> > > >
> > >
> >
> https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=commit;h=ef7308be2a3d6cb38a8c699766c59e951fd2b514
> > > >
> > > > So, it was tagged in some unknown branch, not sure where...
> > > >
> > > > So I'm cherry picking:
> > > >
> > > >
> > >
> >
> https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=commit;h=ef7308be2a3d6cb38a8c699766c59e951fd2b514
> > > >
> > > > Into the 2.8.x branch, and tagging that 2.8.0
> > > >
> > > >
> > > >
> > > >
> > > > On Wed, Jun 19, 2013 at 1:40 PM, Shazron <shazron@gmail.com> wrote:
> > > >
> > > > > Rhetorical question of course I am fixing this...
> > > > >
> > > > >
> > > > > On Wed, Jun 19, 2013 at 1:36 PM, Shazron <shazron@gmail.com>
> wrote:
> > > > >
> > > > >> I noticed in cordova-docs, the 2.8.0 tag was tagged in a commit
on
> > > > >> master, but not in the 2.8.x branch. Furthermore, the commit
that
> > was
> > > > >> tagged is not even in the 2.8.x branch. Do I fix this?
> > > > >>
> > > > >>
> > > > >> On Wed, Jun 19, 2013 at 11:51 AM, Shazron <shazron@gmail.com>
> > wrote:
> > > > >>
> > > > >>> Makes sense. I'll cherry-pick my changes to the relevant
> branches.
> > > > >>>
> > > > >>>
> > > > >>> On Wed, Jun 19, 2013 at 11:45 AM, Michael Brooks <
> > > > >>> michael@michaelbrooks.ca> wrote:
> > > > >>>
> > > > >>>> Hey guys,
> > > > >>>>
> > > > >>>> There is no denying that the release branch practice
is a little
> > odd
> > > > for
> > > > >>>> cordova-docs. This is because the cordova-docs repository
> versions
> > > > >>>> everything by directory (a legacy approach that we will
someday
> > > shift
> > > > >>>> away
> > > > >>>> from).
> > > > >>>>
> > > > >>>> I'll hunt down the release wiki article and update it,
but here
> is
> > > the
> > > > >>>> rundown of the release details:
> > > > >>>>
> > > > >>>> Generating the documentation:
> > > > >>>> ---
> > > > >>>> The documentation is always generated from the master
branch on
> > the
> > > > HEAD
> > > > >>>> commit.
> > > > >>>> The markdown is rendered to HTML as a one-to-one mapping
of the
> > > /docs/
> > > > >>>> directory.
> > > > >>>> Files can be merged together by defining the merge order
in
> > > > >>>> /docs/language/version/config.json
> > > > >>>>
> > > > >>>> Updating the documentation for an upcoming release:
> > > > >>>> ---
> > > > >>>> Always commit into master.
> > > > >>>> When documenting an upcoming release, update the documentation
> > under
> > > > >>>> docs/en/edge/
> > > > >>>>
> > > > >>>> Updating the documentation for a previous release:
> > > > >>>> ---
> > > > >>>> Always commit into master.
> > > > >>>> Update the specific version (e.g. docs/en/2.7.0/)
> > > > >>>> Also update each newer version until edge (e.g. docs/en/2.8.0/
> and
> > > > >>>> docs/en/edge)
> > > > >>>> Cherry-pick to the relevant release branch(es) (e.g.
2.7.x and
> > > 2.8.x)
> > > > >>>> Update each release branch tag to point to your new commit
> > > > >>>>
> > > > >>>> All in all, the release branches are a ceremony that
are only
> used
> > > by
> > > > >>>> coho.
> > > > >>>> However, when cordova-docs is revamped to not include
all
> > versions,
> > > > then
> > > > >>>> the tags and release branches will make a lot more sense.
> > > > Additionally,
> > > > >>>> we'll be happy to have accurate tags for older versions.
> > > > >>>>
> > > > >>>> Michael
> > > > >>>>
> > > > >>>>
> > > > >>>> On Tue, Jun 18, 2013 at 9:34 AM, Shazron <shazron@gmail.com>
> > wrote:
> > > > >>>>
> > > > >>>> > Yeah I'm interested in the flow as well. I think
we published
> > > > >>>> everything
> > > > >>>> > again in older releases, not sure if we are still
doing that
> > going
> > > > >>>> forward
> > > > >>>> >
> > > > >>>> >
> > > > >>>> > On Tue, Jun 18, 2013 at 9:30 AM, Marcel Kinard <
> > > cmarcelk@gmail.com>
> > > > >>>> wrote:
> > > > >>>> >
> > > > >>>> > > On Jun 17, 2013, at 6:21 PM, Shazron <shazron@gmail.com>
> > wrote:
> > > > >>>> > >
> > > > >>>> > > > Should I bother? I know they will go in
edge. There are a
> > > couple
> > > > >>>> of
> > > > >>>> > > issues:
> > > > >>>> > > > https://issues.apache.org/jira/browse/CB-3753
> > > > >>>> > > > https://issues.apache.org/jira/browse/CB-3752
> > > > >>>> > > >
> > > > >>>> > > > Basically it's weird since if I added
it to the 2.8.0
> > folder,
> > > > >>>> it's not
> > > > >>>> > in
> > > > >>>> > > > the 2.8.x branch, but is in master...
> > > > >>>> > > >
> > > > >>>> > > > So for older version updates, I don't
bother with the
> older
> > > > >>>> branches,
> > > > >>>> > > yes?
> > > > >>>> > > > Just master and the older folders
> > > > >>>> > >
> > > > >>>> > > @mwbrooks, when the docs get published to the
web at the end
> > of
> > > > the
> > > > >>>> > > release, does just edge or all version folders
get
> published?
> > > > >>>> > >
> > > > >>>> > > If all folders get published, then correct,
no need to
> commit
> > to
> > > > old
> > > > >>>> > > branches, as all users that browse the docs
online will see
> > your
> > > > >>>> change
> > > > >>>> > in
> > > > >>>> > > the 2.8.0 folder (which is somewhat confusingly
[but
> cleverly]
> > > > from
> > > > >>>> > > master)… unless we ever build a patch release
which doesn't
> > seem
> > > > to
> > > > >>>> > happen,
> > > > >>>> > > with the possible exception of 2.9.x.
> > > > >>>> >
> > > > >>>>
> > > > >>>
> > > > >>>
> > > > >>
> > > > >
> > > >
> > >
> >
>
>
>
> --
> Carlos Santana
> <csantana23@gmail.com>
>

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