cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Brooks <mich...@michaelbrooks.ca>
Subject Re: Documentation update to previous version
Date Wed, 19 Jun 2013 18:45:06 GMT
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