Are there plans for a "*for a saner doc system*" ? --Carlos
On Mon, Jun 24, 2013 at 7:25 PM, Shazron <shaz...@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 <mich...@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 <shaz...@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 <shaz...@gmail.com> wrote: > > > > > > > Rhetorical question of course I am fixing this... > > > > > > > > > > > > On Wed, Jun 19, 2013 at 1:36 PM, Shazron <shaz...@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 <shaz...@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 < > > > >>> mich...@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 <shaz...@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 < > > cmarc...@gmail.com> > > > >>>> wrote: > > > >>>> > > > > >>>> > > On Jun 17, 2013, at 6:21 PM, Shazron <shaz...@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 <csantan...@gmail.com>
