cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brian LeRoux...@brian.io>
Subject Re: Docs for plugins
Date Thu, 01 May 2014 17:17:23 GMT
I'm in agreement here. The registry is the discovery point for the plugin.
People may not use Github (ourselves included) for many plugins.


On Thu, May 1, 2014 at 8:46 AM, Andrew Grieve <agrieve@chromium.org> wrote:

> 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