[NPMCLI-169] CLI should give clear and consistant ERR messages about migrating config to v3 Created: 22/Feb/18  Updated: 09/Mar/18  Resolved: 08/Mar/18

Status: Closed
Project: Magnolia CLI
Component/s: None
Affects Version/s: None
Fix Version/s: 3.0.0

Type: Improvement Priority: Neutral
Reporter: Christopher Zimmermann Assignee: Antonín Juran
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Template:
Acceptance criteria:
Empty
Task DoD:
[ ]* Doc/release notes changes? Comment present?
[ ]* Downstream builds green?
[ ]* Solution information and context easily available?
[ ]* Tests
[ ]* FixVersion filled and not yet released
[ ]  Architecture Decision Record (ADR)
Documentation update required:
Yes
Date of First Response:
Epic Link: CLI v3
Sprint: Kromeriz 136, Kromeriz 137
Story Points: 3

 Description   

We want to reduce the migration pain as much as possible for developers, and provide them with a relatively good experience.
We have two main migration scenarios - the config file & the prototypes - best that developer tackles them both at once.
Whenever we notice an out of date configuration, we should notify the developer in a consistant way. Now we have two detection mechanisms that do different things - one for the jumpstart command, and one for the create commands.

(We need to know the documentation heading for migration to v3. placeholder used below.)

Recommendations (open to additional input/discussion)

Create- commands

  • Create commands should change INFO to ERR "Prototype directory structure has changed in version >= 3.0.0."
  • Docs link should link directly to the migration topic (which still needs to be created). Reason: Ideally user should migrate config file and prototypes at same time.
  • Execution should stop so user does not get the later "_default" does not exist. Reason - user should focus on the migration and not get confused by other stuff.
    ERR! Prototype directory structure has changed in version >= 3.0.0.
    Please migrate both mgnl-cli.json and any customized prototypes to new directory structure.
    See https://documentation.magnolia-cms.com/display/DOCS56/Magnolia+CLI#[migration heading]
    

create-light-module command

  • Also show error about v3 when trying to run "create-light-module"

Jumpstart command

  • Should have similar syntax to the create commands and should also point to magnoila docs.
  • I would remove the how-to tips and the long json snippet, because migration has gotten more complicated - ie they should also remove the big "lightDevFoldersInModule" which is no longer used. They should just go to the docs to learn how to migrate with a best-practice procedure. (which we can easily tune cause its in docs!)
    ERR! Configuration of mgnl-cli.json has changed in version >= 3.0.0.
    Please migrate both mgnl-cli.json and any customized prototypes to new directory structure.
    See https://documentation.magnolia-cms.com/display/DOCS56/Magnolia+CLI#[migration heading]
    

Notes:

Current create command output

info Using configuration at /Users/cz/Documents/a-projects/testing/cli-update-to-3/old-project/mgnl-cli.json
info Using prototypes at /Users/cz/Documents/a-projects/testing/cli-update-to-3/old-project/mgnl-cli-prototypes
info Prototype directory structure has changed in version >= 3.0.0.
info Please migrate your prototypes to new directory structure.
info See https://documentation.magnolia-cms.com/display/DOCS56/Magnolia+CLI#MagnoliaCLI-Prototypes
info No path option provided, component will be created relative to the current folder.
ERR! /Users/cz/Documents/a-projects/testing/cli-update-to-3/old-project/mgnl-cli-prototypes/component/_default doesn't exist. Please ensure that your mgnl-cli-prototypes folder contains prototype with name _default.

Current jumpstart command output:

info Using configuration at /Users/cz/Documents/a-projects/testing/cli-update-to-3/old-project/mgnl-cli.json
info Using prototypes at /Users/cz/Documents/a-projects/testing/cli-update-to-3/old-project/mgnl-cli-prototypes
ERR! Your mgnl-cli.json configuration (/Users/cz/Documents/a-projects/testing/cli-update-to-3/old-project/mgnl-cli.json) does not contain the new resolveArtifactUrl, tomcat and availableWebapps nodes introduced in version 3.0.


Please either:
1. Remove or rename the mgnl-cli.json file and run the “mgnl customize-local-config” command in that directory to recreate the file with the new nodes - and then reapply your customizations, or
2. Edit the mgnl-cli.json file and add the following under the setupMagnolia node (Note that downloadUrl has changed):

  "downloadUrl": "https://nexus.magnolia-cms.com/service/local/artifact/maven/content?r=${repository}&g=${groupId}&a=${artifactId}&e=${extension}&v=${version}",
  "resolveArtifactUrl": "https://nexus.magnolia-cms.com/service/local/artifact/maven/resolve?r=${repository}&g=${groupId}&a=${artifactId}&e=${extension}&v=${version}",
  "tomcat": {
    "repositories": {
      "releases": "magnolia.public.releases",
      "snapshots": "magnolia.public.snapshots"
    },
    "groupId": "info.magnolia.tomcat.barebone",
    "artifactId": "magnolia-tomcat-barebone",
    "extension": "zip",
    "version": "LATEST"
  },
  "availableWebapps": {
    "magnolia-empty-webapp": {
      "repositories": {
        "releases": "magnolia.public.releases",
        "snapshots": "magnolia.public.snapshots"
      },
      "groupId": "info.magnolia",
      "artifactId": "magnolia-empty-webapp"
    },
    "magnolia-community-webapp": {
      "repositories": {
        "releases": "magnolia.public.releases",
        "snapshots": "magnolia.public.snapshots"
      },
      "groupId": "info.magnolia.bundle",
      "artifactId": "magnolia-community-webapp"
    },
    "magnolia-community-demo-webapp": {
      "repositories": {
        "releases": "magnolia.public.releases",
        "snapshots": "magnolia.public.snapshots"
      },
      "groupId": "info.magnolia.bundle",
      "artifactId": "magnolia-community-demo-webapp"
    },
    "magnolia-enterprise-standard-webapp": {
      "repositories": {
        "releases": "magnolia.enterprise.releases",
        "snapshots": "magnolia.enterprise.snapshots"
      },
      "repository": "magnolia.enterprise.releases",
      "groupId": "info.magnolia.eebundle",
      "artifactId": "magnolia-enterprise-standard-webapp"
    },
    "magnolia-enterprise-standard-demo-webapp": {
      "repositories": {
        "releases": "magnolia.enterprise.releases",
        "snapshots": "magnolia.enterprise.snapshots"
      },
      "groupId": "info.magnolia.eebundle",
      "artifactId": "magnolia-enterprise-standard-demo-webapp"
    },
    "magnolia-enterprise-pro-webapp": {
      "repositories": {
        "releases": "magnolia.enterprise.releases",
        "snapshots": "magnolia.enterprise.snapshots"
      },
      "groupId": "info.magnolia.eebundle",
      "artifactId": "magnolia-enterprise-pro-webapp"
    },
    "magnolia-enterprise-pro-demo-webapp": {
      "repositories": {
        "releases": "magnolia.enterprise.releases",
        "snapshots": "magnolia.enterprise.snapshots"
      },
      "groupId": "info.magnolia.eebundle",
      "artifactId": "magnolia-enterprise-pro-demo-webapp"
    },
    "magnolia-now-dev-webapp": {
      "repositories": {
        "releases": "magnolia.enterprise.releases",
        "snapshots": "magnolia.enterprise.snapshots"
      },
      "groupId": "info.magnolia.now",
      "artifactId": "magnolia-now-dev-webapp"
    }
  }



 Comments   
Comment by Christopher Zimmermann [ 22/Feb/18 ]

Migration itself is actually pretty easy.
Rough idea of the migration steps can be found here:
https://wiki.magnolia-cms.com/display/PMTEAM/Notes+for+upgrade+to+version+3

Comment by Christopher Zimmermann [ 27/Feb/18 ]

If someone needs to migrate - then they must migrate BOTH the prototypes and the config file. So i would expect the docs "migration help" would cover both of those topics.

Comment by Christopher Zimmermann [ 28/Feb/18 ]

If possible, I think it would be nice to cover the whole migration on one page, since the process is easiest if you do it all at once. (but not sure if possible)

Comment by Christopher Zimmermann [ 28/Feb/18 ]

Thanks martin.

Generated at Mon Feb 12 04:47:12 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.