+1 for Joerg's comments. There has been a long outstanding bug to create a "Next Steps" guide: https://issues.apache.org/jira/browse/CB-677
I know I personally do not "eat my own dogfood" enough, and I'm sure the same can be said about a lot of us on this list. It can be pretty difficult to even recognize that users are having the problems Joerg describes - we've simply gotten so used to the project that it's hard to "take a step back." This is why mining Stack Overflow and the Google group are huge. Maybe we should send out a survey to the GG asking what kind of "next steps / growing pains" should be listed. I don't think that we necessarily should be writing this documentation ourselves though, but instead linking to various blog articles. See Michael's comment in the JIRA item. Joerg can you please copy your comments into the above JIRA issue? On Tue, Apr 29, 2014 at 4:12 PM, Joe Bowser <bows...@gmail.com> wrote: > +1 to this post, who wants to take this on? > > On Tue, Apr 29, 2014 at 12:22 PM, Joerg Holz <h...@hamburg.de> wrote: > > I’m developing B2B-Apps (iOS and Android), using cordova. > > > > First of all, thank you for your great job. From release to release > things are going easier and tidier. > > > > It is relatively easy for a beginner to start with cordova, but in a > bigger project there are a lot of small jobs and decisions, which have to > be made: The developer has to write clean html, js and css. Has to take > care of: structure of the project, strategy to fall back and restart the > project, testing, ui and ux, perhaps knowledge about a js-framework, > sqlite, the plugin-things, … > > > > It needs a lot of time to get into all this stuff, learning the tricks > and finding a good way for developing. > > > > I know, it ist not your job to teach people how to do all this stuff, > but it would be very helpfully, if there were a page in the documentation > «The steps after the hello world example». Not a tutorial, just a few > sentences and some links to going deeper into hybrid development. > > > > You are the developers of cordova, but there is a need for a bridge to > the «customers» using cordova. (I’m still thinking about starting a blog, > writing down my experiences.) > > > > > > Some suggestions: > > > > – It would be helpful, if cordova could write a «create script», a > special kind of log-file, in the project folder. In this create-script all > steps for recreating the project are listed. > > > > – From the beginner side, it would be much easier to symlink the > www-files in the root to the platform www-files. > > > > – There is a need to write in the documentation on which version of each > platform cordova and the plugins are tested and running. > > > > > > In my opinion, the most important software thing is, to solve the plugin > situation, which are not in the core. I know, it ist not your job, but > there is a need for other plugins and it is horrible to test them. > > > > Cordova is great, but it is not simple as it seems to be. I see a need > to go more into the customer-view. > > > > > > > > Am 29.04.2014 um 20:02 schrieb Ian Clelland <iclell...@chromium.org>: > > > >> Sorry, I'm a little late to the party here... > >> > >> > >> On Mon, Apr 28, 2014 at 4:35 PM, Marcel Kinard <cmarc...@gmail.com> > wrote: > >> > >>> How about this: > >>> > >>> 1) No API changes within a minor version bump. > >> > >> > >> We try (maybe we could do better at this) to follow the guidelines at > >> http://www.semver.org for all of the cordova subprojects, *except* for > the > >> main platform's version number, which we've kind of declared to be a > >> "marketing" version number. > >> > >> According to semver, the rule should be "No API changes with only a > patch > >> version bump. Only backwards-combatible API changes with a minor version > >> bump." In practice, this means that the patch version gets incremented > with > >> bug fixes, and any *new* APIs can be added with a minor version > increment. > >> Any backwards-incompatible changes *require* a major version bump. > >> > >> > >>> For example, we're looking at some "consistency improvements" to the > >>> globalization plugin that would change the return values. That should > >>> trigger a major version bump, even if the signatures/parms don't > change. > >> > >> > >> If the API signatures don't change, then we'd have to consider what *is* > >> changing? If it's just the output, and it's incorrect in version A and > >> correct in version B, then that sounds like a bug fix. If the output is > >> different in a meaningful way then maybe that's minor, maybe major. (I > >> would suggest that it's minor only if the output is definitely *better* > in > >> every case with the new version, but can still be consumed in exactly > the > >> same way) > >> > >> > >>> As a consumer of Cordova, you should be able to have some confidence > that > >>> if there isn't a major version bump, you shouldn't need to change your > >>> calling code. > >>> > >>> > >> Absolutely. If any change to client code is required, there should be a > >> major version bump. (Within reason: any bug could be depended on by > >> someone; see https://xkcd.com/1172/) > >> > >> > >> > >>> 2) When doing an upgrade of plugins or platform, if there is a major > >>> version bump to any of those components, the CLI should make it really > >>> clear (a warning) that there may be a breaking change(s) and give them > the > >>> opportunity to abort the upgrade. > >>> > >> > >> +1. We really need this. Maybe, like Debian, an upgrade should only ever > >> upgrade within the same major release, and a harder upgrade command > would > >> be required for upgrading the major. > >> > >> Of course, this is all wishful thinking right now, since there's no > upgrade > >> command at all. The "upgrade" path is currently "remove plugin; re-add > >> plugin", and I don't think that that flow should ever keep old metadata > >> around. > >> > >> > >>> 3) Keep the Upgrading Guides in the docs complete. So if they want to > look > >>> at what needs to change, these docs should at least give them a feel > for > >>> the order of magnitude, or better yet exactly what would be required. > >>> > >>> We are doing 1 & 3 already, correct? > >>> > >>> On Apr 28, 2014, at 2:49 PM, Josh Soref <jso...@blackberry.com> wrote: > >>> > >>>> Shazron wrote: > >>>> > >>>>> See: > https://groups.google.com/d/msg/phonegap/II0qo-dSFWs/Fj8jkemGSbUJ > >>>> > >>>> While I haven't written it, I've contemplated the metadata required > for > >>> an > >>>> update check that could tell you when a given api breaks. > >>>> > >>>>> because the API for device.platform changed and returned "ios" > instead > >>>>> of "iPhone"/"iPad", > >>>> > >>>> In principle, this would have been flagged to discourage updating the > >>>> plugin, and in theory a solver could have identified the last version > >>> from > >>>> before this break. > >>> > > > > -------------------------------------------------------- > > Jörg Holz | +49-175-640 35 80 > > h...@hamburg.de > > > > NEU: doreport - die Reportingsoftware: > > http://www.doreport.de > > -------------------------------------------------------- > > >
