cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Gill <stevengil...@gmail.com>
Subject Re: What's Stopping us From Independent Platform Releases
Date Wed, 20 Aug 2014 20:59:55 GMT
I still feel it would be a mistake to stop versioning our docs. It would
confuse our users.  It is a norm for projects to have docs associated to
specific versions.

I think docs should be versioned when the cli gets released and
docs.cordova.io should always point to edge. This would address the
splashscreen docs not being live even though the feature has shipped.

This use case can also handle us introducing breaking changes (ex: android
4.0) and not have to keep older docs on edge.

Annotating with "supported in android 3.6.0+" can start looking very ugly
over time if we have lots of annotations all over the place.

As for previous versions, bugs most likely won't be fixed unless it is
something someone volunteers to do. I don't see much value in updating old
versions of docs. But it is worth still having them available for people
using those versions.

I'd like to hear what others think about this?

Both proposals are described at
https://issues.apache.org/jira/browse/CB-7226


On Wed, Aug 20, 2014 at 1:02 PM, Andrew Grieve <agrieve@chromium.org> wrote:

> Just did some pull requests for docs, and wanted to share that I think
> there is really good reason to stop versioning our docs.
>
> - One PR fixed broken links in the 3.5.0 docs that pointed to plugin
> dev branches.
>   --> Any external links in versioned docs may break at any time!
> - One PR was for the new splashscreen support in cordova-lib
>   --> This won't make it out until the next platform release, even
> though it's a shipped feature in CLI!
>
> Versioning our docs has some merit, but it also causes old versions of
> docs to have bugs that don't get fixed, and it adds delays to new
> docs.
>
> Because the things we are documenting are released & versioned
> separately, I think the only sane path forward is to stop versioning
> the docs (and annotate with "supported in android 3.6.0+").
>
> On Thu, Aug 14, 2014 at 5:28 PM, Brian LeRoux <b@brian.io> wrote:
> > Yes, that email was very clearly very rushed! Too much on my plate.
> >
> > The ./bin/create scripts generate 'platform' projects. We need to keep
> > those. They each should use a common seed template for www assets.
> Ideally
> > the platform knows about icons and splashscreens too, so higher level
> > abstracts only need to pass those things down to the platforms. I have no
> > idea where we are with that part. Its always been a headache and one of
> the
> > things keeping ./platforms in version control.
> >
> > Higher up the chain I think we should break out the 'create' part of
> > cordova-lib into a completely separate module that other downstream
> things
> > can use. For example, with PhoneGap Developer Apps you don't need the
> > entire CLI (or any native bits) but just a create command and the
> > phonegap-connect modules for serving the content to the app (app harness
> > flow too).
> >
> >
> >
> >
> > On Thu, Aug 14, 2014 at 12:59 PM, Andrew Grieve <agrieve@chromium.org>
> > wrote:
> >
> >> Could you elaborate Brian? Do you mean to stop support bin/create
> scripts?
> >> Or to have all platforms node-depend on a templates module? Have one
> module
> >> vs one-template-per-platform? Does this apply to both
> icons/splashscreens
> >> as well as default www/?
> >>
> >>
> >> On Thu, Aug 14, 2014 at 3:45 PM, Carlos Santana <csantana23@gmail.com>
> >> wrote:
> >>
> >> > +1 one way of doing it
> >> >
> >> >
> >> > On Thu, Aug 14, 2014 at 1:21 PM, Brian LeRoux <b@brian.io> wrote:
> >> >
> >> > > rather than bundle app-hello-world I'd rather we *extracted*
> >> > > cordova-project-create from cordova-lib into its own module so thing
> >> that
> >> > > create cordova projects only have one way of doing it
> >> > >
> >> > >
> >> > >
> >> > > On Thu, Aug 14, 2014 at 7:58 AM, Carlos Santana <
> csantana23@gmail.com>
> >> > > wrote:
> >> > >
> >> > > > Each platform should carry their default contents including set
of
> >> > icons
> >> > > > and screens for none CLI workflow, the platform can keep taking
> them
> >> > from
> >> > > > app-hello-world as part of it's independent platform release.
> >> > > >
> >> > > > For app-hello-world it should be tag and release with the tools
> (CLI
> >> > > > release) as it's use as the default template for "create"
> >> > > >
> >> > > > Now that I think CLI and config.xml supports icons and screens,
> the
> >> > > default
> >> > > > app created by CLI should include the "res/" icons and screens,
> >> > > including a
> >> > > > config.xml configured with proper values pointing to the images.
> >> > > > This will be easier to end user to figure out on disk what files
> it
> >> > needs
> >> > > > to be modified in the "res/" directory on CLI project.
> >> > > >
> >> > > > This can also be optimized that "res/" contents get populated
as
> the
> >> > > > "cordova platform add" gets executed so user only gets in "res/"
> and
> >> > > > "config.xml" only the platforms added.
> >> > > >
> >> > > > I was looking into this recently as I'm trying to create a new
> >> > universal
> >> > > > www template for IBM Worklight to be use by cordova CLI, but
I got
> >> > brain
> >> > > > stop on how do I create a git repo that includes all my default
> icons
> >> > and
> >> > > > screens that user will replace, but don't want to pollute their
> >> cordova
> >> > > > project with images from a platform their not dealing with yet,
> and
> >> how
> >> > > to
> >> > > > add those icons and screens when they do an "platform add" for
a
> new
> >> > > > platform.
> >> > > >
> >> > > > Maybe this deserves a new thread.
> >> > > >
> >> > > > net is that app-hello-world should be release tad with tools
not
> >> > > platforms
> >> > > > releases.
> >> > > >
> >> > > >
> >> > > >
> >> > > >
> >> > > >
> >> > > > On Thu, Aug 14, 2014 at 9:48 AM, Michal Mocny <
> mmocny@chromium.org>
> >> > > wrote:
> >> > > >
> >> > > > > Does hello-world even need to be versioned at all, then?
 Its
> just
> >> > part
> >> > > > of
> >> > > > > the platform/cli release, and its assets are voted on as
part of
> >> > that?
> >> > > > >
> >> > > > >
> >> > > > > On Thu, Aug 14, 2014 at 9:43 AM, Andrew Grieve <
> >> agrieve@chromium.org
> >> > >
> >> > > > > wrote:
> >> > > > >
> >> > > > > > app-hello-world is quite a weird one now. There's two
parts to
> >> it:
> >> > > > > > 1) default icons & splashscreens - copied into
each platform
> >> > > > > > 2) default www/ - copied into each platform & into
> lazy_load'ed
> >> by
> >> > > CLI
> >> > > > > >
> >> > > > > > For 2) - I think we should stop lazy loading. Maybe
just copy
> it
> >> > into
> >> > > > the
> >> > > > > > CLI repo.
> >> > > > > >
> >> > > > > > For versioning though - I think the repo should be
tagged /
> >> > versioned
> >> > > > > > independently whenever it makes sense.
> >> > > > > >
> >> > > > > >
> >> > > > > > On Thu, Aug 14, 2014 at 9:16 AM, Ian Clelland <
> >> > > iclelland@chromium.org>
> >> > > > > > wrote:
> >> > > > > >
> >> > > > > > > Currently, mobile-spec needs to be tagged with
platform
> >> versions,
> >> > > > since
> >> > > > > > it
> >> > > > > > > contains tests for those platforms, outside of
the plugin
> tests
> >> > > (like
> >> > > > > the
> >> > > > > > > bridge and whitelist tests). As soon as we can
move those
> out,
> >> > then
> >> > > > > > > mobilespec becomes a generic test runner for Cordova,
and we
> >> can
> >> > > just
> >> > > > > tag
> >> > > > > > > it independently of platforms.
> >> > > > > > >
> >> > > > > > >
> >> > > > > > > On Wed, Aug 13, 2014 at 6:12 PM, Steven Gill <
> >> > > stevengill97@gmail.com
> >> > > > >
> >> > > > > > > wrote:
> >> > > > > > >
> >> > > > > > > > New question
> >> > > > > > > >
> >> > > > > > > > How does tagging and versioning for
> cordova-app-hello-world
> >> and
> >> > > > > > > > cordova-mobile-spec look in this new world
of independent
> >> > > releases?
> >> > > > > > > >
> >> > > > > > > > Currently:
> >> > > > > > > >
> >> > > > > > > > 1) They both get branched and tagged at the
beginning of a
> >> > > cadence
> >> > > > > > > release.
> >> > > > > > > > 2) The hello world app is supposed to be
manually copied
> to
> >> > > > platforms
> >> > > > > > if
> >> > > > > > > > changes exist.
> >> > > > > > > >
> >> > > > > > > > Suggestions:
> >> > > > > > > >
> >> > > > > > > > A) They both get tagged independently of
platforms. Won't
> >> > happen
> >> > > > > often
> >> > > > > > > > unless they are changing (the app rarely
changes).
> >> > > > > > > >
> >> > > > > > > > B) They get tagged platform-version when
doing a release.
> So
> >> > > mobile
> >> > > > > > spec
> >> > > > > > > > would have a tag android-3.6.0 when we are
doing the 3.6.0
> >> > > release.
> >> > > > > > > >
> >> > > > > > > > I think we should stop branching for these
two repos.
> Doesn't
> >> > add
> >> > > > > much
> >> > > > > > > > value. The tag will take us back to the state
when the
> >> platform
> >> > > was
> >> > > > > > > > released.
> >> > > > > > > >
> >> > > > > > > > Thoughts? Other suggestions?
> >> > > > > > > >
> >> > > > > > > >
> >> > > > > > > > On Fri, Aug 8, 2014 at 11:26 AM, Andrew Grieve
<
> >> > > > agrieve@chromium.org
> >> > > > > >
> >> > > > > > > > wrote:
> >> > > > > > > >
> >> > > > > > > > > On Tue, Jul 29, 2014 at 5:00 PM, Steven
Gill <
> >> > > > > stevengill97@gmail.com
> >> > > > > > >
> >> > > > > > > > > wrote:
> >> > > > > > > > >
> >> > > > > > > > > > Started creating issues to keep
track of all of these
> >> > things.
> >> > > > > > > > > >
> >> > > > > > > > > > Master issue can be seen at
> >> > > > > > > > > https://issues.apache.org/jira/browse/CB-7221
> >> > > > > > > > > >
> >> > > > > > > > > > Setting CLI to version 4.0.0 sounds
good to me. We can
> >> > > mention
> >> > > > in
> >> > > > > > the
> >> > > > > > > > > > release blog post how platforms
are on their own
> schedule
> >> > > now.
> >> > > > > > > > > >
> >> > > > > > > > > > Option 3 for docs
> >> > > > > > > > > > - Docs get same version as CLI
& get tagged alongside
> cli
> >> > > > > releases
> >> > > > > > > > > > - We can still annotate with "added
in X.X.X, removed
> in
> >> > > X.X.X"
> >> > > > > > where
> >> > > > > > > > it
> >> > > > > > > > > > makes sense. (like the upgrade
guides)
> >> > > > > > > > > > - Point docs.cordova.io to edge
> >> > > > > > > > > > - Dropdown will show tagged versions
> >> > > > > > > > > > Pros:
> >> > > > > > > > > > - Keeps a public history of older
docs at a point in
> >> time.
> >> > > Easy
> >> > > > > to
> >> > > > > > > use
> >> > > > > > > > > for
> >> > > > > > > > > > people who don't want the latest
> >> > > > > > > > > > - Gives us flexibility in changing
docs and not
> worrying
> >> > > about
> >> > > > > > older
> >> > > > > > > > > > versions.
> >> > > > > > > > > >
> >> > > > > > > > > > Thoughts?
> >> > > > > > > > > >
> >> > > > > > > > >
> >> > > > > > > > > Each new version of the docs has significant
space
> >> > requirements
> >> > > > > since
> >> > > > > > > we
> >> > > > > > > > > don't de-dupe images across versions
or translations.
> Not
> >> the
> >> > > end
> >> > > > > of
> >> > > > > > > the
> >> > > > > > > > > world, but the repo is already >
1GB, so it is annoying.
> >> > > > > > > > >
> >> > > > > > > > > I don't think it's common that we delete
docs, so maybe
> we
> >> > > could
> >> > > > > just
> >> > > > > > > > > create new versions when we do purges?
Otherwise, the
> old
> >> > > > versions
> >> > > > > of
> >> > > > > > > > docs
> >> > > > > > > > > just have bugs and are strictly worse
than the newest
> set,
> >> I
> >> > > > think.
> >> > > > > > > > >
> >> > > > > > > > >
> >> > > > > > > > >
> >> > > > > > > > > >
> >> > > > > > > > > > -Steve
> >> > > > > > > > > >
> >> > > > > > > > > >
> >> > > > > > > > > >
> >> > > > > > > > > >
> >> > > > > > > > > >
> >> > > > > > > > > > On Mon, Jul 28, 2014 at 8:26 AM,
Michal Mocny <
> >> > > > > mmocny@chromium.org
> >> > > > > > >
> >> > > > > > > > > wrote:
> >> > > > > > > > > >
> >> > > > > > > > > > > On Mon, Jul 28, 2014 at 5:41
AM, Gorkem Ercan <
> >> > > > > > > > gorkem.ercan@gmail.com>
> >> > > > > > > > > > > wrote:
> >> > > > > > > > > > >
> >> > > > > > > > > > > >
> >> > > > > > > > > > > > This has been discussed
long enough and even for
> >> those
> >> > > > > > downstream
> >> > > > > > > > > > > > distros and tools who
will have to adjust, it is
> >> better
> >> > > to
> >> > > > > > > finalize
> >> > > > > > > > > it.
> >> > > > > > > > > > > >
> >> > > > > > > > > > > > Overall I like the plan,
my major concern was with
> >> > > cadence
> >> > > > > > > > releaeses
> >> > > > > > > > > > > gone,
> >> > > > > > > > > > > > the lack of a
> >> > > > > > > > > > > > name/tag/version number
for Cordova, and a
> >> description
> >> > of
> >> > > > its
> >> > > > > > > > > contents.
> >> > > > > > > > > > > > Now, this is
> >> > > > > > > > > > > > addressed with CLI and
package.json file.
> >> > > > > > > > > > > >
> >> > > > > > > > > > > > My +1 for this.
> >> > > > > > > > > > > >
> >> > > > > > > > > > > >
> >> > > > > > > > > > > > On Fri, Jul 25, 2014
at 05:25:28PM -0400, Andrew
> >> Grieve
> >> > > > > wrote:
> >> > > > > > > > > > > > > Wanted to start
a thread for everyone to share
> what
> >> > > > > concrete
> >> > > > > > > > > changes
> >> > > > > > > > > > > > they'd
> >> > > > > > > > > > > > > like to see happen
before we start having
> platforms
> >> > > being
> >> > > > > > > > released
> >> > > > > > > > > in
> >> > > > > > > > > > > an
> >> > > > > > > > > > > > > unsynchronized fashion.
> >> > > > > > > > > > > > >
> >> > > > > > > > > > > > > I'll start :)
> >> > > > > > > > > > > > >
> >> > > > > > > > > > > > > cordova-js:
> >> > > > > > > > > > > > >  - cordova.version
returns a value computed from
> >> the
> >> > > > > > cordova-js
> >> > > > > > > > git
> >> > > > > > > > > > > tag.
> >> > > > > > > > > > > > >    - Let's deprecate
this field
> >> > > > > > > > > > > > >    - And create
"cordova.platformVersion"
> >> > > > > > > > > > > > >    - And update
our release process to have the
> >> > version
> >> > > > set
> >> > > > > > > based
> >> > > > > > > > > on
> >> > > > > > > > > > > the
> >> > > > > > > > > > > > > platform's version
rather than the tag within
> >> > > cordova-js.
> >> > > > > > > > > > > >
> >> > > > > > > > > > > > What will be the value
for cordova.version during
> >> > > > deprecation
> >> > > > > > > > period?
> >> > > > > > > > > > > >
> >> > > > > > > > > > > > >
> >> > > > > > > > > > > > > Cordova-docs:
> >> > > > > > > > > > > > >  - Most of the docs
are not actually affected by
> >> > > platform
> >> > > > > > > > versions.
> >> > > > > > > > > > > > >  - Mainly though,
it's the platform guides that
> >> are.
> >> > > > > > > > > > > > >  - Two options that
I see:
> >> > > > > > > > > > > > >    - 1) Set default
version to "edge" & always
> >> > annotate
> >> > > > > with
> >> > > > > > > > "added
> >> > > > > > > > > > in
> >> > > > > > > > > > > > > X.X.X, removed in
X.X.X"
> >> > > > > > > > > > > > >    - 2) Move guides
to live in platform repos
> and
> >> > link
> >> > > to
> >> > > > > > them
> >> > > > > > > > from
> >> > > > > > > > > > > docs.
> >> > > > > > > > > > > > >
> >> > > > > > > > > > > > > cordova-cli:
> >> > > > > > > > > > > > >   - Set version
to 4.0.0 just to make it so
> that it
> >> > > > doesn't
> >> > > > > > map
> >> > > > > > > > to
> >> > > > > > > > > > any
> >> > > > > > > > > > > > > existing platform
versions
> >> > > > > > > > > > > >
> >> > > > > > > > > > > > Not sure if this matters.
Platforms will catch up
> to
> >> > > 4.0.0
> >> > > > > soon
> >> > > > > > > > > enough.
> >> > > > > > > > > > > >
> >> > > > > > > > > > >
> >> > > > > > > > > > > CLI version is currently "3.5.0-0.2.7-dev".
 We
> need to
> >> > > > change
> >> > > > > it
> >> > > > > > > to
> >> > > > > > > > > > > something thats valid semver,
and preferably
> somewhat
> >> > > > > compatible
> >> > > > > > > with
> >> > > > > > > > > the
> >> > > > > > > > > > > previous versions.  Choices
I think are:
> >> > > > > > > > > > > - 3.6.0
> >> > > > > > > > > > > - 4.0.0
> >> > > > > > > > > > > - A Complete reset
> >> > > > > > > > > > >
> >> > > > > > > > > > > I'm also in favour of 4.0.0
given those options.
> >> > > > > > > > > > >
> >> > > > > > > > > > > I am mildly concerned that
with the looming 4.0
> >> releases
> >> > of
> >> > > > > > > > platforms,
> >> > > > > > > > > > > users will think this is a
cad-ver update and not
> >> > > appreciate
> >> > > > > the
> >> > > > > > > > change
> >> > > > > > > > > > of
> >> > > > > > > > > > > strategy, but partially think
that may be a good
> thing
> >> > too
> >> > > > > (slow
> >> > > > > > > > > > > comfortable transition).
> >> > > > > > > > > > >
> >> > > > > > > > > > >
> >> > > > > > > > > > > >
> >> > > > > > > > > > > > >
> >> > > > > > > > > > > > > Release Process:
> >> > > > > > > > > > > > >   - Tag cordova-js
for each platform release
> with
> >> > > > > > > > > "PLATFORM-VERSION"
> >> > > > > > > > > > > > >   - Rewrite
> >> > > > > > > > > > > > >
> >> > > > > > > > > > > >
> >> > > > > > > > > > >
> >> > > > > > > > > >
> >> > > > > > > > >
> >> > > > > > > >
> >> > > > > > >
> >> > > > > >
> >> > > > >
> >> > > >
> >> > >
> >> >
> >>
> https://github.com/apache/cordova-coho/blob/master/docs/cadence-release-process.md
> >> > > > > > > > > > > > > as "platforms-release-process"
> >> > > > > > > > > > > >
> >> > > > > > > > > > >
> >> > > > > > > > > >
> >> > > > > > > > >
> >> > > > > > > >
> >> > > > > > >
> >> > > > > >
> >> > > > >
> >> > > >
> >> > > >
> >> > > >
> >> > > > --
> >> > > > Carlos Santana
> >> > > > <csantana23@gmail.com>
> >> > > >
> >> > >
> >> >
> >> >
> >> >
> >> > --
> >> > Carlos Santana
> >> > <csantana23@gmail.com>
> >> >
> >>
>

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