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 17:21:51 GMT
Hi Freak,

We're just talking about cordova core plugins (not all plugins). You can
find the plugin registry here: http://plugins.cordova.io


On Thu, May 1, 2014 at 1:19 PM, Freak Show <freakshow42@me.com> wrote:

> Ok, well looking at the docs, I don't actually know how to get a list of
> "registered" plugins.
>
> So if you're going to use a registry - it needs to be a lot easier to see,
> search, and use.
>
> On May 1, 2014, at 10:17 AM, Brian LeRoux <b@brian.io> wrote:
>
> > 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