Re: Documentation update to previous version
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 wrote: > Are there plans for a "*for a saner doc system*" ? > > --Carlos > > > > On Mon, Jun 24, 2013 at 7:25 PM, Shazron 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 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 wrote: > > > > > > > > > Rhetorical question of course I am fixing this... > > > > > > > > > > > > > > > On Wed, Jun 19, 2013 at 1:36 PM, Shazron > 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 > > 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 l
Re: Documentation update to previous version
Are there plans for a "*for a saner doc system*" ? --Carlos On Mon, Jun 24, 2013 at 7:25 PM, Shazron 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 >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 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 wrote: > > > > > > > Rhetorical question of course I am fixing this... > > > > > > > > > > > > On Wed, Jun 19, 2013 at 1:36 PM, Shazron 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 > 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 > 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 > wrote: > > > > > > > > > > > Should I bother?
Re: Documentation update to previous version
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 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 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 wrote: > > > > > Rhetorical question of course I am fixing this... > > > > > > > > > On Wed, Jun 19, 2013 at 1:36 PM, Shazron 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 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 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 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
Re: Documentation update to previous version
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 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 wrote: > > > Rhetorical question of course I am fixing this... > > > > > > On Wed, Jun 19, 2013 at 1:36 PM, Shazron 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 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 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 > wrote: > > > > > On Jun 17, 2013, at 6:21 PM, Shazron 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. > > > > >>> > >>> > >> > > >
Re: Documentation update to previous version
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 wrote: > Rhetorical question of course I am fixing this... > > > On Wed, Jun 19, 2013 at 1:36 PM, Shazron 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 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 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 wrote: > > > On Jun 17, 2013, at 6:21 PM, Shazron 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. > >>> >>> >> >
Re: Documentation update to previous version
Rhetorical question of course I am fixing this... On Wed, Jun 19, 2013 at 1:36 PM, Shazron 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 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 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 >>> wrote: >>> > >>> > > On Jun 17, 2013, at 6:21 PM, Shazron 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. >>> > >>> >> >> >
Re: Documentation update to previous version
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 wrote: > Makes sense. I'll cherry-pick my changes to the relevant branches. > > > On Wed, Jun 19, 2013 at 11:45 AM, Michael Brooks > 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 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 >> wrote: >> > >> > > On Jun 17, 2013, at 6:21 PM, Shazron 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. >> > >> > >
Re: Documentation update to previous version
Makes sense. I'll cherry-pick my changes to the relevant branches. On Wed, Jun 19, 2013 at 11:45 AM, Michael Brooks 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 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 > wrote: > > > > > On Jun 17, 2013, at 6:21 PM, Shazron 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. > > >
Re: Documentation update to previous version
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 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 wrote: > > > On Jun 17, 2013, at 6:21 PM, Shazron 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. >
Re: Documentation update to previous version
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 wrote: > On Jun 17, 2013, at 6:21 PM, Shazron 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.
Re: Documentation update to previous version
On Jun 17, 2013, at 6:21 PM, Shazron 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.
Documentation update to previous version
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
