Details

    • Type: Improvement Improvement
    • Status: Resolved
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 1.0.0, 1.1.0, 1.2.0, 1.3.0, 1.4.0, 1.5.0, 1.6.0, 1.6.1, 1.7.0, 1.8.0
    • Fix Version/s: 2.0.0
    • Component/s: Docs
    • Labels:
      None

      Description

      Guidance of migrating an old PhoneGap project to a new version is not easy to find. It would be nice to have resources identifying how to upgrade a project that are easily accessible on the web (docs or phonegap download page) - this could be simple instructions which libraries to swap out, and what JS files have changed. Since there isn't much content out and easy to find now, this probably would go a long way to help PhoneGap users who want to upgrade to a newer SDK.
      (Feedback based on communication with Adobe customers)

      There are no Sub-Tasks for this issue.

        Activity

        Hide
        Filip Maj added a comment -

        Holy shit... 63 subtasks/guides. Awesome work everyone.

        Show
        Filip Maj added a comment - Holy shit... 63 subtasks/guides. Awesome work everyone.
        Hide
        Michael Brooks added a comment -

        All platforms have implemented migration guides from 1.0.0-1.8.0

        Show
        Michael Brooks added a comment - All platforms have implemented migration guides from 1.0.0-1.8.0
        Hide
        Michael Brooks added a comment -

        I've added a placeholder to the edge documentation for upgrading each platform. I've also updated the 1.8.0 tickets for each platform with a link to the index.md file that must be completed.

        Show
        Michael Brooks added a comment - I've added a placeholder to the edge documentation for upgrading each platform. I've also updated the 1.8.0 tickets for each platform with a link to the index.md file that must be completed.
        Hide
        Michael Brooks added a comment -

        Awesome suggestion Andrew and I agree, Apache Cordova needs to document this better.

        I'll start by creating sub-tasks for each platform and each release version. I think it's best to start small - as you mentioned - by documenting how to swap the binary libraries and JavaScript files. Afterwards, we can get into the gritty details of each platform (e.g. introduction of plugins.xml).

        Fil and I have decided to add the basic migration guides to the 1.8 milestone.

        Show
        Michael Brooks added a comment - Awesome suggestion Andrew and I agree, Apache Cordova needs to document this better. I'll start by creating sub-tasks for each platform and each release version. I think it's best to start small - as you mentioned - by documenting how to swap the binary libraries and JavaScript files. Afterwards, we can get into the gritty details of each platform (e.g. introduction of plugins.xml ). Fil and I have decided to add the basic migration guides to the 1.8 milestone.
        Hide
        Filip Maj added a comment -

        Yep, totally. We are on the same page here Andrew.

        Keep tabs on this issue to track progress with the guides. We will be adding guides to the docs repo, which in turn will be deployed to http://docs.phonegap.com.

        Show
        Filip Maj added a comment - Yep, totally. We are on the same page here Andrew. Keep tabs on this issue to track progress with the guides. We will be adding guides to the docs repo , which in turn will be deployed to http://docs.phonegap.com .
        Hide
        Andrew Trice added a comment -

        I agree, what is there is great, and extremely helpful. I wasn't critiquing the work that has been done. What I am suggesting is that it be more easily found online. I am aware that the content is in the dmg, but not everyone looks there, they look online/to Google first. I am suggesting that we make it easier to find this same information online.

        Currently, the workflow to find this is to download the zip file, go to lib/ios/, open the DMG, then go to "guides". This isn't intuitive or easy to find - (not a criticism of any work that has been done to date). Typically users open the DMG, run the installer, close the DMG, then never open it again.

        What I am hearing from people who are currently using PhoneGap is that they didn't even know this content existed, so we should make it easier for them to find.

        Show
        Andrew Trice added a comment - I agree, what is there is great, and extremely helpful. I wasn't critiquing the work that has been done. What I am suggesting is that it be more easily found online. I am aware that the content is in the dmg, but not everyone looks there, they look online/to Google first. I am suggesting that we make it easier to find this same information online. Currently, the workflow to find this is to download the zip file, go to lib/ios/, open the DMG, then go to "guides". This isn't intuitive or easy to find - (not a criticism of any work that has been done to date). Typically users open the DMG, run the installer, close the DMG, then never open it again. What I am hearing from people who are currently using PhoneGap is that they didn't even know this content existed, so we should make it easier for them to find.
        Hide
        Filip Maj added a comment -

        Shaz has already been doing a great job writing migration guides for each version for iOS.

        Let's keep this issue as the top-level issue for migration guides as a whole in cordova. The docs should house guides for upgrading projects between specific versions.

        We should create sub-tasks in this issue for each platform, for each missing version of the guide (ideally we will write guides for previous versions as well). We still have tons of users on 1.2, 1.3, 1.4.1, etc., and they are not upgrading due to, among other things, lack of guidance in this area.

        Need to stub out markdown files in the docs for these upgrade guides.

        Show
        Filip Maj added a comment - Shaz has already been doing a great job writing migration guides for each version for iOS. Let's keep this issue as the top-level issue for migration guides as a whole in cordova. The docs should house guides for upgrading projects between specific versions. We should create sub-tasks in this issue for each platform, for each missing version of the guide (ideally we will write guides for previous versions as well). We still have tons of users on 1.2, 1.3, 1.4.1, etc., and they are not upgrading due to, among other things, lack of guidance in this area. Need to stub out markdown files in the docs for these upgrade guides.
        Hide
        Brian LeRoux added a comment -

        yes, shaz can you work w/ micheal to get this into the guides section of the docs?

        Show
        Brian LeRoux added a comment - yes, shaz can you work w/ micheal to get this into the guides section of the docs?
        Hide
        Andrew Trice added a comment -

        Again, Brian asked me to enter this as a bug... The content is not easily found when searching for it. This feedback is coming from Adobe customers already invested in PhoneGap/Cordova.

        Show
        Andrew Trice added a comment - Again, Brian asked me to enter this as a bug... The content is not easily found when searching for it. This feedback is coming from Adobe customers already invested in PhoneGap/Cordova.
        Hide
        Shazron Abdullah added a comment -

        There is a Guides folder in the .dmg distribution with various guides - also viewable in GitHub. Currently this is written by a dev (me). If a technical writer wants to take this on, that will be great - it's open sourced as Markdown files.

        Show
        Shazron Abdullah added a comment - There is a Guides folder in the .dmg distribution with various guides - also viewable in GitHub. Currently this is written by a dev (me). If a technical writer wants to take this on, that will be great - it's open sourced as Markdown files.

          People

          • Assignee:
            Michael Brooks
            Reporter:
            Andrew Trice
          • Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development