cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Grieve <agri...@chromium.org>
Subject Re: Docs for plugins
Date Thu, 01 May 2014 15:46:34 GMT
I think we want to steer people to the plugin registry rather than github.




On Thu, May 1, 2014 at 10:48 AM, Ian Clelland <iclelland@chromium.org>wrote:

> I was referring to 'egde' docs for Cordova itself; there certainly aren't
> any 'edge' docs on the plugin registry, since by design it only knows about
> released plugins, and as you say, edge docs there would require watching
> repos, which seems out-of-scope.
>
> Since we already *do* have edge docs on
> http://cordova.apache.org/docs/en/edge/, I was just considering whether we
> should try to link those to the corresponding plugin docs on GitHub, rather
> than linking to only released plugins.
>
>
> On Thu, May 1, 2014 at 10:00 AM, Michal Mocny <mmocny@chromium.org> wrote:
>
> > I think generally mapping [plugin_id, engine_version] -> [plugin_version]
> > sounds like a useful plugin registry feature to support, especially so
> that
> > you can install latest compatible plugin versions using old CLI versions.
> >  We can  leverage that same mapping for docs exactly as you describe.
> >
> > Regarding "edge" docs, are they necessary at all?  If you want to
> install a
> > plugin from source, you can read the docs from source.  If we want to
> > publish "edge" docs because the latest plugin release had typos, we
> should
> > consider doing point releases for docs fixes (unlikely, but hey).  If we
> > tell users to just read "edge" for highest quality docs, they may be
> > reading docs on api's that don't apply to any actual release.
> >
> > Anyway, if we do want "edge", it would require watching/cloning git
> repos,
> > and I think the registry right now only uses uploaded tarballs.  A
> low-road
> > solution could be to have nightly cron job that uploads an "edge" tarball
> > for core plugins?
> >
> >
> > On Thu, May 1, 2014 at 9:04 AM, Ian Clelland <iclelland@chromium.org>
> > wrote:
> >
> > > I was considering doing two things:
> > >
> > > 1. Point the edge docs back to GitHub/master, so that edge doesn't have
> > to
> > > point to released plugin docs. (I think this is more in the _spirit_ of
> > the
> > > edge docs, but it means more work to actually release versioned docs)
> > >
> > > 2. Add a feature to plugins.cordova.io that could return the best
> > matching
> > > plugin version, based on an engine version in the URL. That way, the
> > 3.4.0
> > > docs could point to something like "
> > >
> >
> http://plugins.cordova.io/#/package/org.apache.cordova.camera;engine=3.4.0
> > > "
> > > and get the docs page for the best version of the camera plugin for
> > *that*
> > > cordova release.
> > >
> > > Thoughts?
> > >
> > > On Wednesday, April 30, 2014, Michal Mocny <mmocny@chromium.org>
> wrote:
> > >
> > > > Thats will be easy to pretend (just kidding! ;).  Yes, the plugin
> > > registry
> > > > shows the docs as they exist at the time of the plugin release, so
> next
> > > > release the docs will be up to date.
> > > >
> > > > The primary benefit here is that the plugin registry has a version
> > > switcher
> > > > on the side, and you'll get to see the docs as they existed for that
> > > > version.
> > > >
> > > > (for the future, we could consider adding "edge" versions for core
> > > plugins
> > > > on plugin registry.  Not for installs, but just to list the latest
> > docs)
> > > >
> > > >
> > > > On Wed, Apr 30, 2014 at 9:54 AM, Ray Camden <raycamde@adobe.com>
> > wrote:
> > > >
> > > > > So... pretend I'm dumb here. Do I need to do anything? Will it just
> > be
> > > > > updated in the next plugin release?
> > > > >
> > > > > ________________________________________
> > > > > From: mmocny@google.com <mmocny@google.com> on behalf of Michal
> > Mocny
> > > <
> > > > > mmocny@chromium.org>
> > > > > Sent: Wednesday, April 30, 2014 8:50 AM
> > > > > To: Michal Mocny
> > > > > Cc: dev
> > > > > Subject: Re: Docs for plugins
> > > > >
> > > > > Ray, Yeah seems file plugin @c1a1052 was tagged for 1.1.0 release
> 13
> > > days
> > > > > ago, you patched docs after that tag @abcaf70 12 days ago, and
> plugin
> > > was
> > > > > actually released with @e9efe65 7 days ago.  You just missed the
> > window
> > > > > narrowly!
> > > > >
> > > > > -Michal
> > > > >
> > > > >
> > > > > On Wed, Apr 30, 2014 at 9:45 AM, Michal Mocny <mmocny@chromium.org
> >
> > > > wrote:
> > > > >
> > > > > > I believe the plugin docs reflect what was bundled with the
> latest
> > > > plugin
> > > > > > release -- perhaps your recent changes were not released yet?
 Or
> > has
> > > > > > something gotten lost in the recent shuffle with dev/master
> > branches?
> > > > > >
> > > > > > Its true, though, that for core plugins our registry links to
the
> > > > > official
> > > > > > apache repos and not the github mirrors, and the official repo
> > links
> > > do
> > > > > not
> > > > > > have a pretty renderers for markdown docs.  Not sure what we
want
> > to
> > > do
> > > > > > here.
> > > > > >
> > > > > >
> > > > > > On Wed, Apr 30, 2014 at 9:14 AM, Ray Camden <raycamde@adobe.com>
> > > > wrote:
> > > > > >
> > > > > >> I just noticed that the links for plugins from docs.cordova.iogo
> > > to
> > > > a
> > > > > >> new page (
> > > > http://plugins.cordova.io/#/package/org.apache.cordova.fileas
> > > > > >> an example). The docs for this one in particular seem wrong.
I
> > > > recently
> > > > > did
> > > > > >> a small mod to add the error codes to the docs, and I'm
not
> seeing
> > > it
> > > > > here.
> > > > > >> Mistake? Do I need to make a new PR on the repo?
> > > > > >>
> > > > > >> Related - why is the link to the github version gone?
> > > > > >
> > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>

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