RE: Upgrading Guides
I'm renaming it "Using Plugman to Manage Plugins". I'll take care of the x-ref on that page. --Mike S From: Shazron [shaz...@gmail.com] Sent: Wednesday, July 17, 2013 4:12 PM To: dev@cordova.apache.org Subject: Re: Upgrading Guides What should the reference to the plugman doc be? I can follow the WP upgrade docs, but that part is not there yet I don't think. https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=blob;f=docs/en/edge/guide/platforms/wp8/upgrading.md;h=6d8f37ea10a424f7a72b2f32051ff341790710db;hb=HEAD On Wed, Jul 17, 2013 at 1:06 PM, Michael Sierra wrote: > I committed a change to the CLI doc that details plugin add/rm/ls based on > this doc. The plugman interface should be doc'ed separately to avoid > confusion. Am editing the plugman doc a bit & will figure out where to > place it, but I'd like to confirm the overall use case. I see it as: you > want to upgrade to 3.0, which requires you to add plugins for device APIs, > but for whatever reason you aren't running the CLI yet. Are there any more > specific scenarios? > > As for the Upgrading Guides, any step up to 3.0 we doc should reference > the CLI, perhaps with a separate/additional non-CLI upgrade path that > references the plugman doc. I'd use "Upgrading Windows Phone" as a model. > > --Mike S > > > From: Shazron [shaz...@gmail.com] > Sent: Tuesday, July 16, 2013 7:59 PM > To: dev@cordova.apache.org > Subject: Re: Upgrading Guides > > For https://issues.apache.org/jira/browse/CB-4222 > > I added this note at the bottom of the 2.9.0 -> 3.0.0 Upgrading Guide for > iOS: > > NOTE: Starting with Cordova 3.0.0, projects do not come with any plugins, > you will have to install the ones you require for your project using the > `plugman` CLI utility - see the Core Plugin Install Guide. > > Note the currently non-existent "Core Plugin Install Guide" which is common > for all platforms. I talked to Steve, this doc should show two methods - > the Cordova CLI way and the plugman way of how to install the core plugins. > Since the Upgrading Guides are for legacy methods, it refers to the plugman > way. > > Mike Sierra, not sure if this is a good method or we should cram everything > into the CLI doc. > > > On Tue, Jul 16, 2013 at 2:14 PM, Andrew Grieve > wrote: > > > +1 document both, but we should be clear that CLI is the new fancy and > will > > eventually become the only supported (whatever that means) workflow at > some > > point in the future. > > > > > > On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser wrote: > > > > > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI > > wrote: > > > > I think we should document both. > > > > > > But we've already done the CLI docs. :P > > > > > > > > > > > > > > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser > > wrote: > > > > > > > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve < > agri...@chromium.org> > > > >> wrote: > > > >> > The CLI guide reads quite well! Great work whoever put it > together! > > :) > > > >> > > > > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just > write > > a > > > >> > single "CLI" upgrade guide instead of writing one for each > platform > > > >> (might > > > >> > need caveats per-platform still). > > > >> > > > > >> > Should we document how to create plugman-only projects as well as > > CLI > > > >> > projects? If so, we'll need a good top-level explainer page that > > > explains > > > >> > the difference. If not, then I don't think we should mention it in > > our > > > >> > readme. I'm hoping that we can document only the CLI flow so that > > > there > > > >> > will be less diversity in project structures out there, and it > will > > > let > > > >> us > > > >> > focus on doing one thing well. > > > >> > > > > >> > > > >> I think we should document plugman-only projects, because that's > what > > > >> exists today. It's much easier to start to use plugman for a > project > > > >> than to use the CLI, especially if you've done your own > modifications > > > >> to the Java code in your Cordova project, which a few people have > > > >> done. I see nothing here that helps our existing users maintain > their > > > >> codebases. If this project teaches you anything, it should teach > you > > > >> that just because you want people to use your project a certain way, > > > >> it doesn't mean that they will. > > > >> > > > > > >
Re: Upgrading Guides
What should the reference to the plugman doc be? I can follow the WP upgrade docs, but that part is not there yet I don't think. https://git-wip-us.apache.org/repos/asf?p=cordova-docs.git;a=blob;f=docs/en/edge/guide/platforms/wp8/upgrading.md;h=6d8f37ea10a424f7a72b2f32051ff341790710db;hb=HEAD On Wed, Jul 17, 2013 at 1:06 PM, Michael Sierra wrote: > I committed a change to the CLI doc that details plugin add/rm/ls based on > this doc. The plugman interface should be doc'ed separately to avoid > confusion. Am editing the plugman doc a bit & will figure out where to > place it, but I'd like to confirm the overall use case. I see it as: you > want to upgrade to 3.0, which requires you to add plugins for device APIs, > but for whatever reason you aren't running the CLI yet. Are there any more > specific scenarios? > > As for the Upgrading Guides, any step up to 3.0 we doc should reference > the CLI, perhaps with a separate/additional non-CLI upgrade path that > references the plugman doc. I'd use "Upgrading Windows Phone" as a model. > > --Mike S > > > From: Shazron [shaz...@gmail.com] > Sent: Tuesday, July 16, 2013 7:59 PM > To: dev@cordova.apache.org > Subject: Re: Upgrading Guides > > For https://issues.apache.org/jira/browse/CB-4222 > > I added this note at the bottom of the 2.9.0 -> 3.0.0 Upgrading Guide for > iOS: > > NOTE: Starting with Cordova 3.0.0, projects do not come with any plugins, > you will have to install the ones you require for your project using the > `plugman` CLI utility - see the Core Plugin Install Guide. > > Note the currently non-existent "Core Plugin Install Guide" which is common > for all platforms. I talked to Steve, this doc should show two methods - > the Cordova CLI way and the plugman way of how to install the core plugins. > Since the Upgrading Guides are for legacy methods, it refers to the plugman > way. > > Mike Sierra, not sure if this is a good method or we should cram everything > into the CLI doc. > > > On Tue, Jul 16, 2013 at 2:14 PM, Andrew Grieve > wrote: > > > +1 document both, but we should be clear that CLI is the new fancy and > will > > eventually become the only supported (whatever that means) workflow at > some > > point in the future. > > > > > > On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser wrote: > > > > > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI > > wrote: > > > > I think we should document both. > > > > > > But we've already done the CLI docs. :P > > > > > > > > > > > > > > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser > > wrote: > > > > > > > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve < > agri...@chromium.org> > > > >> wrote: > > > >> > The CLI guide reads quite well! Great work whoever put it > together! > > :) > > > >> > > > > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just > write > > a > > > >> > single "CLI" upgrade guide instead of writing one for each > platform > > > >> (might > > > >> > need caveats per-platform still). > > > >> > > > > >> > Should we document how to create plugman-only projects as well as > > CLI > > > >> > projects? If so, we'll need a good top-level explainer page that > > > explains > > > >> > the difference. If not, then I don't think we should mention it in > > our > > > >> > readme. I'm hoping that we can document only the CLI flow so that > > > there > > > >> > will be less diversity in project structures out there, and it > will > > > let > > > >> us > > > >> > focus on doing one thing well. > > > >> > > > > >> > > > >> I think we should document plugman-only projects, because that's > what > > > >> exists today. It's much easier to start to use plugman for a > project > > > >> than to use the CLI, especially if you've done your own > modifications > > > >> to the Java code in your Cordova project, which a few people have > > > >> done. I see nothing here that helps our existing users maintain > their > > > >> codebases. If this project teaches you anything, it should teach > you > > > >> that just because you want people to use your project a certain way, > > > >> it doesn't mean that they will. > > > >> > > > > > >
RE: Upgrading Guides
I committed a change to the CLI doc that details plugin add/rm/ls based on this doc. The plugman interface should be doc'ed separately to avoid confusion. Am editing the plugman doc a bit & will figure out where to place it, but I'd like to confirm the overall use case. I see it as: you want to upgrade to 3.0, which requires you to add plugins for device APIs, but for whatever reason you aren't running the CLI yet. Are there any more specific scenarios? As for the Upgrading Guides, any step up to 3.0 we doc should reference the CLI, perhaps with a separate/additional non-CLI upgrade path that references the plugman doc. I'd use "Upgrading Windows Phone" as a model. --Mike S From: Shazron [shaz...@gmail.com] Sent: Tuesday, July 16, 2013 7:59 PM To: dev@cordova.apache.org Subject: Re: Upgrading Guides For https://issues.apache.org/jira/browse/CB-4222 I added this note at the bottom of the 2.9.0 -> 3.0.0 Upgrading Guide for iOS: NOTE: Starting with Cordova 3.0.0, projects do not come with any plugins, you will have to install the ones you require for your project using the `plugman` CLI utility - see the Core Plugin Install Guide. Note the currently non-existent "Core Plugin Install Guide" which is common for all platforms. I talked to Steve, this doc should show two methods - the Cordova CLI way and the plugman way of how to install the core plugins. Since the Upgrading Guides are for legacy methods, it refers to the plugman way. Mike Sierra, not sure if this is a good method or we should cram everything into the CLI doc. On Tue, Jul 16, 2013 at 2:14 PM, Andrew Grieve wrote: > +1 document both, but we should be clear that CLI is the new fancy and will > eventually become the only supported (whatever that means) workflow at some > point in the future. > > > On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser wrote: > > > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI > wrote: > > > I think we should document both. > > > > But we've already done the CLI docs. :P > > > > > > > > > > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser > wrote: > > > > > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve > > >> wrote: > > >> > The CLI guide reads quite well! Great work whoever put it together! > :) > > >> > > > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just write > a > > >> > single "CLI" upgrade guide instead of writing one for each platform > > >> (might > > >> > need caveats per-platform still). > > >> > > > >> > Should we document how to create plugman-only projects as well as > CLI > > >> > projects? If so, we'll need a good top-level explainer page that > > explains > > >> > the difference. If not, then I don't think we should mention it in > our > > >> > readme. I'm hoping that we can document only the CLI flow so that > > there > > >> > will be less diversity in project structures out there, and it will > > let > > >> us > > >> > focus on doing one thing well. > > >> > > > >> > > >> I think we should document plugman-only projects, because that's what > > >> exists today. It's much easier to start to use plugman for a project > > >> than to use the CLI, especially if you've done your own modifications > > >> to the Java code in your Cordova project, which a few people have > > >> done. I see nothing here that helps our existing users maintain their > > >> codebases. If this project teaches you anything, it should teach you > > >> that just because you want people to use your project a certain way, > > >> it doesn't mean that they will. > > >> > > >
Re: Upgrading Guides
I have pushed the first draft of coreplugininstall.md to docs under the plugins folder for now. I am not sure what the best directory to have it under is and I need to make sure that some of the links in it work. Would love someone to look over it (Mike Sierra maybe?) On Tue, Jul 16, 2013 at 5:35 PM, Brian LeRoux wrote: > Yar > On Jul 16, 2013 5:23 PM, "Andrew Grieve" wrote: > > > SGTM as well. > > > > > > On Tue, Jul 16, 2013 at 8:02 PM, Filip Maj wrote: > > > > > SGTM! > > > > > > On 7/16/13 4:59 PM, "Shazron" wrote: > > > > > > >For https://issues.apache.org/jira/browse/CB-4222 > > > > > > > >I added this note at the bottom of the 2.9.0 -> 3.0.0 Upgrading Guide > > for > > > >iOS: > > > > > > > >NOTE: Starting with Cordova 3.0.0, projects do not come with any > > plugins, > > > >you will have to install the ones you require for your project using > the > > > >`plugman` CLI utility - see the Core Plugin Install Guide. > > > > > > > >Note the currently non-existent "Core Plugin Install Guide" which is > > > >common > > > >for all platforms. I talked to Steve, this doc should show two > methods - > > > >the Cordova CLI way and the plugman way of how to install the core > > > >plugins. > > > >Since the Upgrading Guides are for legacy methods, it refers to the > > > >plugman > > > >way. > > > > > > > >Mike Sierra, not sure if this is a good method or we should cram > > > >everything > > > >into the CLI doc. > > > > > > > > > > > >On Tue, Jul 16, 2013 at 2:14 PM, Andrew Grieve > > > >wrote: > > > > > > > >> +1 document both, but we should be clear that CLI is the new fancy > and > > > >>will > > > >> eventually become the only supported (whatever that means) workflow > at > > > >>some > > > >> point in the future. > > > >> > > > >> > > > >> On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser > > wrote: > > > >> > > > >> > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI > > > > >> wrote: > > > >> > > I think we should document both. > > > >> > > > > >> > But we've already done the CLI docs. :P > > > >> > > > > >> > > > > > >> > > > > > >> > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser > > > > >> wrote: > > > >> > > > > > >> > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve > > > >> > > > >> > >> wrote: > > > >> > >> > The CLI guide reads quite well! Great work whoever put it > > > >>together! > > > >> :) > > > >> > >> > > > > >> > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just > > > >>write > > > >> a > > > >> > >> > single "CLI" upgrade guide instead of writing one for each > > > >>platform > > > >> > >> (might > > > >> > >> > need caveats per-platform still). > > > >> > >> > > > > >> > >> > Should we document how to create plugman-only projects as > well > > as > > > >> CLI > > > >> > >> > projects? If so, we'll need a good top-level explainer page > > that > > > >> > explains > > > >> > >> > the difference. If not, then I don't think we should mention > it > > > >>in > > > >> our > > > >> > >> > readme. I'm hoping that we can document only the CLI flow so > > that > > > >> > there > > > >> > >> > will be less diversity in project structures out there, and > it > > > >>will > > > >> > let > > > >> > >> us > > > >> > >> > focus on doing one thing well. > > > >> > >> > > > > >> > >> > > > >> > >> I think we should document plugman-only projects, because > that's > > > >>what > > > >> > >> exists today. It's much easier to start to use plugman for a > > > >>project > > > >> > >> than to use the CLI, especially if you've done your own > > > >>modifications > > > >> > >> to the Java code in your Cordova project, which a few people > have > > > >> > >> done. I see nothing here that helps our existing users > maintain > > > >>their > > > >> > >> codebases. If this project teaches you anything, it should > teach > > > >>you > > > >> > >> that just because you want people to use your project a certain > > > >>way, > > > >> > >> it doesn't mean that they will. > > > >> > >> > > > >> > > > > >> > > > > > > > > >
Re: Upgrading Guides
Yar On Jul 16, 2013 5:23 PM, "Andrew Grieve" wrote: > SGTM as well. > > > On Tue, Jul 16, 2013 at 8:02 PM, Filip Maj wrote: > > > SGTM! > > > > On 7/16/13 4:59 PM, "Shazron" wrote: > > > > >For https://issues.apache.org/jira/browse/CB-4222 > > > > > >I added this note at the bottom of the 2.9.0 -> 3.0.0 Upgrading Guide > for > > >iOS: > > > > > >NOTE: Starting with Cordova 3.0.0, projects do not come with any > plugins, > > >you will have to install the ones you require for your project using the > > >`plugman` CLI utility - see the Core Plugin Install Guide. > > > > > >Note the currently non-existent "Core Plugin Install Guide" which is > > >common > > >for all platforms. I talked to Steve, this doc should show two methods - > > >the Cordova CLI way and the plugman way of how to install the core > > >plugins. > > >Since the Upgrading Guides are for legacy methods, it refers to the > > >plugman > > >way. > > > > > >Mike Sierra, not sure if this is a good method or we should cram > > >everything > > >into the CLI doc. > > > > > > > > >On Tue, Jul 16, 2013 at 2:14 PM, Andrew Grieve > > >wrote: > > > > > >> +1 document both, but we should be clear that CLI is the new fancy and > > >>will > > >> eventually become the only supported (whatever that means) workflow at > > >>some > > >> point in the future. > > >> > > >> > > >> On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser > wrote: > > >> > > >> > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI > > >> wrote: > > >> > > I think we should document both. > > >> > > > >> > But we've already done the CLI docs. :P > > >> > > > >> > > > > >> > > > > >> > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser > > >> wrote: > > >> > > > > >> > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve > > >> > > >> > >> wrote: > > >> > >> > The CLI guide reads quite well! Great work whoever put it > > >>together! > > >> :) > > >> > >> > > > >> > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just > > >>write > > >> a > > >> > >> > single "CLI" upgrade guide instead of writing one for each > > >>platform > > >> > >> (might > > >> > >> > need caveats per-platform still). > > >> > >> > > > >> > >> > Should we document how to create plugman-only projects as well > as > > >> CLI > > >> > >> > projects? If so, we'll need a good top-level explainer page > that > > >> > explains > > >> > >> > the difference. If not, then I don't think we should mention it > > >>in > > >> our > > >> > >> > readme. I'm hoping that we can document only the CLI flow so > that > > >> > there > > >> > >> > will be less diversity in project structures out there, and it > > >>will > > >> > let > > >> > >> us > > >> > >> > focus on doing one thing well. > > >> > >> > > > >> > >> > > >> > >> I think we should document plugman-only projects, because that's > > >>what > > >> > >> exists today. It's much easier to start to use plugman for a > > >>project > > >> > >> than to use the CLI, especially if you've done your own > > >>modifications > > >> > >> to the Java code in your Cordova project, which a few people have > > >> > >> done. I see nothing here that helps our existing users maintain > > >>their > > >> > >> codebases. If this project teaches you anything, it should teach > > >>you > > >> > >> that just because you want people to use your project a certain > > >>way, > > >> > >> it doesn't mean that they will. > > >> > >> > > >> > > > >> > > > > >
Re: Upgrading Guides
SGTM as well. On Tue, Jul 16, 2013 at 8:02 PM, Filip Maj wrote: > SGTM! > > On 7/16/13 4:59 PM, "Shazron" wrote: > > >For https://issues.apache.org/jira/browse/CB-4222 > > > >I added this note at the bottom of the 2.9.0 -> 3.0.0 Upgrading Guide for > >iOS: > > > >NOTE: Starting with Cordova 3.0.0, projects do not come with any plugins, > >you will have to install the ones you require for your project using the > >`plugman` CLI utility - see the Core Plugin Install Guide. > > > >Note the currently non-existent "Core Plugin Install Guide" which is > >common > >for all platforms. I talked to Steve, this doc should show two methods - > >the Cordova CLI way and the plugman way of how to install the core > >plugins. > >Since the Upgrading Guides are for legacy methods, it refers to the > >plugman > >way. > > > >Mike Sierra, not sure if this is a good method or we should cram > >everything > >into the CLI doc. > > > > > >On Tue, Jul 16, 2013 at 2:14 PM, Andrew Grieve > >wrote: > > > >> +1 document both, but we should be clear that CLI is the new fancy and > >>will > >> eventually become the only supported (whatever that means) workflow at > >>some > >> point in the future. > >> > >> > >> On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser wrote: > >> > >> > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI > >> wrote: > >> > > I think we should document both. > >> > > >> > But we've already done the CLI docs. :P > >> > > >> > > > >> > > > >> > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser > >> wrote: > >> > > > >> > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve > >> > >> > >> wrote: > >> > >> > The CLI guide reads quite well! Great work whoever put it > >>together! > >> :) > >> > >> > > >> > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just > >>write > >> a > >> > >> > single "CLI" upgrade guide instead of writing one for each > >>platform > >> > >> (might > >> > >> > need caveats per-platform still). > >> > >> > > >> > >> > Should we document how to create plugman-only projects as well as > >> CLI > >> > >> > projects? If so, we'll need a good top-level explainer page that > >> > explains > >> > >> > the difference. If not, then I don't think we should mention it > >>in > >> our > >> > >> > readme. I'm hoping that we can document only the CLI flow so that > >> > there > >> > >> > will be less diversity in project structures out there, and it > >>will > >> > let > >> > >> us > >> > >> > focus on doing one thing well. > >> > >> > > >> > >> > >> > >> I think we should document plugman-only projects, because that's > >>what > >> > >> exists today. It's much easier to start to use plugman for a > >>project > >> > >> than to use the CLI, especially if you've done your own > >>modifications > >> > >> to the Java code in your Cordova project, which a few people have > >> > >> done. I see nothing here that helps our existing users maintain > >>their > >> > >> codebases. If this project teaches you anything, it should teach > >>you > >> > >> that just because you want people to use your project a certain > >>way, > >> > >> it doesn't mean that they will. > >> > >> > >> > > >> > >
Re: Upgrading Guides
SGTM! On 7/16/13 4:59 PM, "Shazron" wrote: >For https://issues.apache.org/jira/browse/CB-4222 > >I added this note at the bottom of the 2.9.0 -> 3.0.0 Upgrading Guide for >iOS: > >NOTE: Starting with Cordova 3.0.0, projects do not come with any plugins, >you will have to install the ones you require for your project using the >`plugman` CLI utility - see the Core Plugin Install Guide. > >Note the currently non-existent "Core Plugin Install Guide" which is >common >for all platforms. I talked to Steve, this doc should show two methods - >the Cordova CLI way and the plugman way of how to install the core >plugins. >Since the Upgrading Guides are for legacy methods, it refers to the >plugman >way. > >Mike Sierra, not sure if this is a good method or we should cram >everything >into the CLI doc. > > >On Tue, Jul 16, 2013 at 2:14 PM, Andrew Grieve >wrote: > >> +1 document both, but we should be clear that CLI is the new fancy and >>will >> eventually become the only supported (whatever that means) workflow at >>some >> point in the future. >> >> >> On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser wrote: >> >> > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI >> wrote: >> > > I think we should document both. >> > >> > But we've already done the CLI docs. :P >> > >> > > >> > > >> > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser >> wrote: >> > > >> > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve >> >> > >> wrote: >> > >> > The CLI guide reads quite well! Great work whoever put it >>together! >> :) >> > >> > >> > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just >>write >> a >> > >> > single "CLI" upgrade guide instead of writing one for each >>platform >> > >> (might >> > >> > need caveats per-platform still). >> > >> > >> > >> > Should we document how to create plugman-only projects as well as >> CLI >> > >> > projects? If so, we'll need a good top-level explainer page that >> > explains >> > >> > the difference. If not, then I don't think we should mention it >>in >> our >> > >> > readme. I'm hoping that we can document only the CLI flow so that >> > there >> > >> > will be less diversity in project structures out there, and it >>will >> > let >> > >> us >> > >> > focus on doing one thing well. >> > >> > >> > >> >> > >> I think we should document plugman-only projects, because that's >>what >> > >> exists today. It's much easier to start to use plugman for a >>project >> > >> than to use the CLI, especially if you've done your own >>modifications >> > >> to the Java code in your Cordova project, which a few people have >> > >> done. I see nothing here that helps our existing users maintain >>their >> > >> codebases. If this project teaches you anything, it should teach >>you >> > >> that just because you want people to use your project a certain >>way, >> > >> it doesn't mean that they will. >> > >> >> > >>
Re: Upgrading Guides
For https://issues.apache.org/jira/browse/CB-4222 I added this note at the bottom of the 2.9.0 -> 3.0.0 Upgrading Guide for iOS: NOTE: Starting with Cordova 3.0.0, projects do not come with any plugins, you will have to install the ones you require for your project using the `plugman` CLI utility - see the Core Plugin Install Guide. Note the currently non-existent "Core Plugin Install Guide" which is common for all platforms. I talked to Steve, this doc should show two methods - the Cordova CLI way and the plugman way of how to install the core plugins. Since the Upgrading Guides are for legacy methods, it refers to the plugman way. Mike Sierra, not sure if this is a good method or we should cram everything into the CLI doc. On Tue, Jul 16, 2013 at 2:14 PM, Andrew Grieve wrote: > +1 document both, but we should be clear that CLI is the new fancy and will > eventually become the only supported (whatever that means) workflow at some > point in the future. > > > On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser wrote: > > > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI > wrote: > > > I think we should document both. > > > > But we've already done the CLI docs. :P > > > > > > > > > > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser > wrote: > > > > > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve > > >> wrote: > > >> > The CLI guide reads quite well! Great work whoever put it together! > :) > > >> > > > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just write > a > > >> > single "CLI" upgrade guide instead of writing one for each platform > > >> (might > > >> > need caveats per-platform still). > > >> > > > >> > Should we document how to create plugman-only projects as well as > CLI > > >> > projects? If so, we'll need a good top-level explainer page that > > explains > > >> > the difference. If not, then I don't think we should mention it in > our > > >> > readme. I'm hoping that we can document only the CLI flow so that > > there > > >> > will be less diversity in project structures out there, and it will > > let > > >> us > > >> > focus on doing one thing well. > > >> > > > >> > > >> I think we should document plugman-only projects, because that's what > > >> exists today. It's much easier to start to use plugman for a project > > >> than to use the CLI, especially if you've done your own modifications > > >> to the Java code in your Cordova project, which a few people have > > >> done. I see nothing here that helps our existing users maintain their > > >> codebases. If this project teaches you anything, it should teach you > > >> that just because you want people to use your project a certain way, > > >> it doesn't mean that they will. > > >> > > >
Re: Upgrading Guides
+1 document both, but we should be clear that CLI is the new fancy and will eventually become the only supported (whatever that means) workflow at some point in the future. On Tue, Jul 16, 2013 at 5:00 PM, Joe Bowser wrote: > On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI wrote: > > I think we should document both. > > But we've already done the CLI docs. :P > > > > > > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser wrote: > > > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve > >> wrote: > >> > The CLI guide reads quite well! Great work whoever put it together! :) > >> > > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just write a > >> > single "CLI" upgrade guide instead of writing one for each platform > >> (might > >> > need caveats per-platform still). > >> > > >> > Should we document how to create plugman-only projects as well as CLI > >> > projects? If so, we'll need a good top-level explainer page that > explains > >> > the difference. If not, then I don't think we should mention it in our > >> > readme. I'm hoping that we can document only the CLI flow so that > there > >> > will be less diversity in project structures out there, and it will > let > >> us > >> > focus on doing one thing well. > >> > > >> > >> I think we should document plugman-only projects, because that's what > >> exists today. It's much easier to start to use plugman for a project > >> than to use the CLI, especially if you've done your own modifications > >> to the Java code in your Cordova project, which a few people have > >> done. I see nothing here that helps our existing users maintain their > >> codebases. If this project teaches you anything, it should teach you > >> that just because you want people to use your project a certain way, > >> it doesn't mean that they will. > >> >
Re: Upgrading Guides
On Tue, Jul 16, 2013 at 1:41 PM, Anis KADRI wrote: > I think we should document both. But we've already done the CLI docs. :P > > > On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser wrote: > >> On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve >> wrote: >> > The CLI guide reads quite well! Great work whoever put it together! :) >> > >> > Just occurred to me that for 3.0 -> 3.1, we can probably just write a >> > single "CLI" upgrade guide instead of writing one for each platform >> (might >> > need caveats per-platform still). >> > >> > Should we document how to create plugman-only projects as well as CLI >> > projects? If so, we'll need a good top-level explainer page that explains >> > the difference. If not, then I don't think we should mention it in our >> > readme. I'm hoping that we can document only the CLI flow so that there >> > will be less diversity in project structures out there, and it will let >> us >> > focus on doing one thing well. >> > >> >> I think we should document plugman-only projects, because that's what >> exists today. It's much easier to start to use plugman for a project >> than to use the CLI, especially if you've done your own modifications >> to the Java code in your Cordova project, which a few people have >> done. I see nothing here that helps our existing users maintain their >> codebases. If this project teaches you anything, it should teach you >> that just because you want people to use your project a certain way, >> it doesn't mean that they will. >>
Re: Upgrading Guides
I think we should document both. On Tue, Jul 16, 2013 at 11:48 AM, Joe Bowser wrote: > On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve > wrote: > > The CLI guide reads quite well! Great work whoever put it together! :) > > > > Just occurred to me that for 3.0 -> 3.1, we can probably just write a > > single "CLI" upgrade guide instead of writing one for each platform > (might > > need caveats per-platform still). > > > > Should we document how to create plugman-only projects as well as CLI > > projects? If so, we'll need a good top-level explainer page that explains > > the difference. If not, then I don't think we should mention it in our > > readme. I'm hoping that we can document only the CLI flow so that there > > will be less diversity in project structures out there, and it will let > us > > focus on doing one thing well. > > > > I think we should document plugman-only projects, because that's what > exists today. It's much easier to start to use plugman for a project > than to use the CLI, especially if you've done your own modifications > to the Java code in your Cordova project, which a few people have > done. I see nothing here that helps our existing users maintain their > codebases. If this project teaches you anything, it should teach you > that just because you want people to use your project a certain way, > it doesn't mean that they will. >
Re: Upgrading Guides
On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve wrote: > The CLI guide reads quite well! Great work whoever put it together! :) > > Just occurred to me that for 3.0 -> 3.1, we can probably just write a > single "CLI" upgrade guide instead of writing one for each platform (might > need caveats per-platform still). > > Should we document how to create plugman-only projects as well as CLI > projects? If so, we'll need a good top-level explainer page that explains > the difference. If not, then I don't think we should mention it in our > readme. I'm hoping that we can document only the CLI flow so that there > will be less diversity in project structures out there, and it will let us > focus on doing one thing well. > I think we should document plugman-only projects, because that's what exists today. It's much easier to start to use plugman for a project than to use the CLI, especially if you've done your own modifications to the Java code in your Cordova project, which a few people have done. I see nothing here that helps our existing users maintain their codebases. If this project teaches you anything, it should teach you that just because you want people to use your project a certain way, it doesn't mean that they will.
RE: Upgrading Guides
I'll add links to the CLI doc from each Upgrading doc, then expand the CLI doc a bit to discuss in general terms how to upgrade from a non-CLI project. Not familiar with any platform-specific variations, info about which would belong on each platform's Upgrading Guide, but I assume it's basically: create a new project; then move in the assets. And thanks for the nice comment, Andrew. --Mike S From: Shazron [shaz...@gmail.com] Sent: Tuesday, July 16, 2013 12:58 PM To: dev@cordova.apache.org Subject: Re: Upgrading Guides What Andrew said - I would think us documenting the CLI way would be adequate Will there be people that only work on one platform and want to use plugman on its own in their existing project structure? Yes, we just point them to the plugman docs I suppose. The upgrading document is great Benn, thanks! However, I feel it is incomplete (speaking for iOS) for the majority of our users. They have no clue on how to install the core plugins, we have to either add explicit instructions on how to add a core plugin based on the release tarball (which will include the core plugins as source), or just install from the canonical git repo URL (not sure about plugin discovery by name here?) It's should be a separate doc maybe, but there could be a guide on how to upgrade from a non-CLI structured project to a CLI structured one. On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve wrote: > The CLI guide reads quite well! Great work whoever put it together! :) > > Just occurred to me that for 3.0 -> 3.1, we can probably just write a > single "CLI" upgrade guide instead of writing one for each platform (might > need caveats per-platform still). > > Should we document how to create plugman-only projects as well as CLI > projects? If so, we'll need a good top-level explainer page that explains > the difference. If not, then I don't think we should mention it in our > readme. I'm hoping that we can document only the CLI flow so that there > will be less diversity in project structures out there, and it will let us > focus on doing one thing well. > > > On Tue, Jul 16, 2013 at 2:50 AM, Filip Maj wrote: > > > That looks good Benn. The upgrading docs should look almost identical > > across platforms, and I think you've started it well (the big bold note > > about having to add the old core apis as plugins now). > > > > A few things that I think need doing for those docs to be complete: > > > > - Plugins need READMEs. I imagine most of them will look identical other > > than particular ids and file references. Instructions on how to install > > the plugin manually, with plugman, and with cordova-cli should be > provided > > in there. > > > I don't think we want to tell them how to install the plugin manually. What > would that even look like? > > - Link to the plugins in the upgrading guides, from there users can look > > at the readmes to install them. > > - The "upgrading with cordova cli" section can then be expanded with > > specific commands to run to install all of the core plugins and get the > > same app state as in pre-3.0. Maybe add notes to encourage the user to > > think about which apis are really necessary for them in their app. > > > > Let me know how that sounds folks and I can add that to the windows phone > > upgrading guide. From there the other platforms can follow suit with the > > same general upgrading notes. > > > > On 7/15/13 8:15 PM, "Benn Mapes" wrote: > > > > >There is a document that talks about the cordova-cli : > > > > > > https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/cli/ > > >index.md > > > > > >But I don't see any mention of how to install the core plugins (or any > > >plugins...) > > > > > >For the windows phone upgrade guides I did something like this : > > > > > > https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/plat > > >forms/wp8/upgrading.md > > > > > >But I feel we might need a little bit more elaboration on this. > > > > > > > > >On Mon, Jul 15, 2013 at 6:58 PM, Shazron wrote: > > > > > >> What's the story here? I assume we all have a common one, in that we > > >> require the user to install cordova-cli through npm, etc and instruct > > >>them > > >> on how to add the core plugins using this tool. > > >> > > >> Have I missed a doc somewhere already written? (probably) > > >> > > > > >
Re: Upgrading Guides
What Andrew said - I would think us documenting the CLI way would be adequate Will there be people that only work on one platform and want to use plugman on its own in their existing project structure? Yes, we just point them to the plugman docs I suppose. The upgrading document is great Benn, thanks! However, I feel it is incomplete (speaking for iOS) for the majority of our users. They have no clue on how to install the core plugins, we have to either add explicit instructions on how to add a core plugin based on the release tarball (which will include the core plugins as source), or just install from the canonical git repo URL (not sure about plugin discovery by name here?) It's should be a separate doc maybe, but there could be a guide on how to upgrade from a non-CLI structured project to a CLI structured one. On Tue, Jul 16, 2013 at 6:21 AM, Andrew Grieve wrote: > The CLI guide reads quite well! Great work whoever put it together! :) > > Just occurred to me that for 3.0 -> 3.1, we can probably just write a > single "CLI" upgrade guide instead of writing one for each platform (might > need caveats per-platform still). > > Should we document how to create plugman-only projects as well as CLI > projects? If so, we'll need a good top-level explainer page that explains > the difference. If not, then I don't think we should mention it in our > readme. I'm hoping that we can document only the CLI flow so that there > will be less diversity in project structures out there, and it will let us > focus on doing one thing well. > > > On Tue, Jul 16, 2013 at 2:50 AM, Filip Maj wrote: > > > That looks good Benn. The upgrading docs should look almost identical > > across platforms, and I think you've started it well (the big bold note > > about having to add the old core apis as plugins now). > > > > A few things that I think need doing for those docs to be complete: > > > > - Plugins need READMEs. I imagine most of them will look identical other > > than particular ids and file references. Instructions on how to install > > the plugin manually, with plugman, and with cordova-cli should be > provided > > in there. > > > I don't think we want to tell them how to install the plugin manually. What > would that even look like? > > - Link to the plugins in the upgrading guides, from there users can look > > at the readmes to install them. > > - The "upgrading with cordova cli" section can then be expanded with > > specific commands to run to install all of the core plugins and get the > > same app state as in pre-3.0. Maybe add notes to encourage the user to > > think about which apis are really necessary for them in their app. > > > > Let me know how that sounds folks and I can add that to the windows phone > > upgrading guide. From there the other platforms can follow suit with the > > same general upgrading notes. > > > > On 7/15/13 8:15 PM, "Benn Mapes" wrote: > > > > >There is a document that talks about the cordova-cli : > > > > > > https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/cli/ > > >index.md > > > > > >But I don't see any mention of how to install the core plugins (or any > > >plugins...) > > > > > >For the windows phone upgrade guides I did something like this : > > > > > > https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/plat > > >forms/wp8/upgrading.md > > > > > >But I feel we might need a little bit more elaboration on this. > > > > > > > > >On Mon, Jul 15, 2013 at 6:58 PM, Shazron wrote: > > > > > >> What's the story here? I assume we all have a common one, in that we > > >> require the user to install cordova-cli through npm, etc and instruct > > >>them > > >> on how to add the core plugins using this tool. > > >> > > >> Have I missed a doc somewhere already written? (probably) > > >> > > > > >
RE: Upgrading Guides
FYI: I split the "Upgrading Guide" into more digestible platform-specific docs available under "Platform Guides" (edge/guide/platforms/*/upgrading.md). I haven't yet scrutinized whether the content is still relevant, but that's a good idea to note the CLI-based workflow. For now I'll link the CLI guide from from each as applicable. (Slightly complicated b/c not all platforms are supported by CLI.) --Mike S From: Shazron [shaz...@gmail.com] Sent: Monday, July 15, 2013 9:58 PM To: dev@cordova.apache.org Subject: Upgrading Guides What's the story here? I assume we all have a common one, in that we require the user to install cordova-cli through npm, etc and instruct them on how to add the core plugins using this tool. Have I missed a doc somewhere already written? (probably)
Re: Upgrading Guides
The CLI guide reads quite well! Great work whoever put it together! :) Just occurred to me that for 3.0 -> 3.1, we can probably just write a single "CLI" upgrade guide instead of writing one for each platform (might need caveats per-platform still). Should we document how to create plugman-only projects as well as CLI projects? If so, we'll need a good top-level explainer page that explains the difference. If not, then I don't think we should mention it in our readme. I'm hoping that we can document only the CLI flow so that there will be less diversity in project structures out there, and it will let us focus on doing one thing well. On Tue, Jul 16, 2013 at 2:50 AM, Filip Maj wrote: > That looks good Benn. The upgrading docs should look almost identical > across platforms, and I think you've started it well (the big bold note > about having to add the old core apis as plugins now). > > A few things that I think need doing for those docs to be complete: > > - Plugins need READMEs. I imagine most of them will look identical other > than particular ids and file references. Instructions on how to install > the plugin manually, with plugman, and with cordova-cli should be provided > in there. > I don't think we want to tell them how to install the plugin manually. What would that even look like? - Link to the plugins in the upgrading guides, from there users can look > at the readmes to install them. > - The "upgrading with cordova cli" section can then be expanded with > specific commands to run to install all of the core plugins and get the > same app state as in pre-3.0. Maybe add notes to encourage the user to > think about which apis are really necessary for them in their app. > > Let me know how that sounds folks and I can add that to the windows phone > upgrading guide. From there the other platforms can follow suit with the > same general upgrading notes. > > On 7/15/13 8:15 PM, "Benn Mapes" wrote: > > >There is a document that talks about the cordova-cli : > > > https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/cli/ > >index.md > > > >But I don't see any mention of how to install the core plugins (or any > >plugins...) > > > >For the windows phone upgrade guides I did something like this : > > > https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/plat > >forms/wp8/upgrading.md > > > >But I feel we might need a little bit more elaboration on this. > > > > > >On Mon, Jul 15, 2013 at 6:58 PM, Shazron wrote: > > > >> What's the story here? I assume we all have a common one, in that we > >> require the user to install cordova-cli through npm, etc and instruct > >>them > >> on how to add the core plugins using this tool. > >> > >> Have I missed a doc somewhere already written? (probably) > >> > >
Re: Upgrading Guides
That looks good Benn. The upgrading docs should look almost identical across platforms, and I think you've started it well (the big bold note about having to add the old core apis as plugins now). A few things that I think need doing for those docs to be complete: - Plugins need READMEs. I imagine most of them will look identical other than particular ids and file references. Instructions on how to install the plugin manually, with plugman, and with cordova-cli should be provided in there. - Link to the plugins in the upgrading guides, from there users can look at the readmes to install them. - The "upgrading with cordova cli" section can then be expanded with specific commands to run to install all of the core plugins and get the same app state as in pre-3.0. Maybe add notes to encourage the user to think about which apis are really necessary for them in their app. Let me know how that sounds folks and I can add that to the windows phone upgrading guide. From there the other platforms can follow suit with the same general upgrading notes. On 7/15/13 8:15 PM, "Benn Mapes" wrote: >There is a document that talks about the cordova-cli : >https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/cli/ >index.md > >But I don't see any mention of how to install the core plugins (or any >plugins...) > >For the windows phone upgrade guides I did something like this : >https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/plat >forms/wp8/upgrading.md > >But I feel we might need a little bit more elaboration on this. > > >On Mon, Jul 15, 2013 at 6:58 PM, Shazron wrote: > >> What's the story here? I assume we all have a common one, in that we >> require the user to install cordova-cli through npm, etc and instruct >>them >> on how to add the core plugins using this tool. >> >> Have I missed a doc somewhere already written? (probably) >>
Re: Upgrading Guides
There is a document that talks about the cordova-cli : https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/cli/index.md But I don't see any mention of how to install the core plugins (or any plugins...) For the windows phone upgrade guides I did something like this : https://github.com/apache/cordova-docs/blob/master/docs/en/edge/guide/platforms/wp8/upgrading.md But I feel we might need a little bit more elaboration on this. On Mon, Jul 15, 2013 at 6:58 PM, Shazron wrote: > What's the story here? I assume we all have a common one, in that we > require the user to install cordova-cli through npm, etc and instruct them > on how to add the core plugins using this tool. > > Have I missed a doc somewhere already written? (probably) >
