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 Mon, 24 Jun 2013 23:25:03 GMT
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.
> > >>>> >
> > >>>>
> > >>>
> > >>>
> > >>
> > >
> >
>

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