I think we can also use a combination of these. For small changes where it makes sense, just push to master and be conscious of its effect on the current tools release out in the wild. If the change is significant and inline documentation gets hairy, just create a branch.
A side benefit of doing more and master and getting it into the eyes of users is earlier feedback on what's coming up. Either way, whatever we chose, lowering process overhead is what we need right now. Lets just do what feels natural and leads for devs actually focusing on docs! On Mon, Jul 14, 2014 at 11:27 AM, Max Woghiren <m...@chromium.org> wrote: > Okay, so here are the current proposals for handling Ray's issue (thanks > Ray!): > > 1. Update docs at commit-time and release-time. At commit-time, > documentation changes can be marked with "coming soon", or "removed in next > release", or whatever the relevant message is. At release-time, docs are > further updated to remove these sub-messages. > > 2. Use CSS to do the manual marking in proposal 1. We could also use it to > hide certain documentation changes until release. > > 3. Create a docs branch for each releasable component. Whenever a > component is released, merge that branch into master. > > Does anyone feel strongly about any of these or have another suggestion? > > > On Fri, Jul 11, 2014 at 2:57 PM, Andrew Grieve <agri...@chromium.org> > wrote: > > > Good point Ray. > > > > Another option would be to create a branch-per-component e.g. tools, > > android, ios, etc. that changes go into, and then merge into master from > > the branch that corresponds to the release that is happening > > > > > > On Fri, Jul 11, 2014 at 2:02 PM, Michal Mocny <mmo...@chromium.org> > wrote: > > > > > Ray, but I thought we always wanted more cowbell? > > > > > > Sorry, had to. I agree with Ray here, but I would also want to see > > latest > > > fixes to docs that apply to released version. > > > > > > Suggestion: rely on discipline to markup documentation changes which > only > > > apply to development versions? > > > > > > e.g. > > > > > > <div class="available-in-4.0"> > > > Now with more ---cowbell! > > > </div> > > > > > > And part of release instructions is to change styling from looking > > > scary/experimental to looking ordinary? > > > > > > -Michal > > > > > > > > > On Fri, Jul 11, 2014 at 1:51 PM, Ray Camden <rayca...@adobe.com> > wrote: > > > > > > > Ok, so let me rephrase then. Imagine the next version of the CLI adds > > > > cowbell support: > > > > > > > > cordova cowbell --epic > > > > > > > > but this is NOT in the release version. > > > > > > > > If I go to docs.cordova.io, click on The Command Line Interface, > will > > I > > > > see cowbell documented? If so, I think that is a mistake. > > > > > > > > ________________________________________ > > > > From: agri...@google.com <agri...@google.com> on behalf of Andrew > > > Grieve < > > > > agri...@chromium.org> > > > > Sent: Friday, July 11, 2014 11:39 AM > > > > To: dev > > > > Subject: Re: Pointing docs to edge > > > > > > > > Yeah, plugin docs are already gone from docs.cordova.io. This change > > is > > > > strictly for guides & platform docs. The main motivation here is that > > it > > > > doesn't make sense to have versioned docs if platform versions > diverge > > > > anyways. It actually already makes little sense for the tools guides, > > > since > > > > they are released more often the platforms. > > > > > > > > > > > > On Fri, Jul 11, 2014 at 12:36 PM, Max Woghiren <m...@chromium.org> > > > wrote: > > > > > > > > > My understanding is that plugin docs live in plugin repos and will > be > > > > > versioned alongside the plugins themselves. They'll be removed > from > > > > > docs.cordova.io. > > > > > > > > > > > > > > > On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden <rayca...@adobe.com> > > > wrote: > > > > > > > > > > > Is edge what people use when they get the latest version of > cordova > > > or > > > > a > > > > > > plugin? If not, I'd strongly argue against it. > > > > > > > > > > > > If I download the Camera plugin, I expect the default docs to > match > > > > whats > > > > > > shipped in that version. > > > > > > > > > > > > ________________________________________ > > > > > > From: m...@google.com <m...@google.com> on behalf of Max > Woghiren > > < > > > > > > m...@chromium.org> > > > > > > Sent: Friday, July 11, 2014 10:46 AM > > > > > > To: dev > > > > > > Subject: Pointing docs to edge > > > > > > > > > > > > Just wanted to bring back this conversation—how does everyone > feel > > > > about > > > > > > switching docs.cordova.io to point to edge? There has been some > > > > > > discussion > > > > > > about cutting versioned docs after 3.5.0, and we're approaching a > > > good > > > > > time > > > > > > to do it. :) > > > > > > > > > > > > > > > > > > > > >
