From 59dda53aa2748f6e8993e85453a2ccbc4cd47c30 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Wed, 17 Apr 2019 15:55:08 +0100 Subject: [PATCH 01/12] Blueprints Update --- text/0000-blueprints-update.md | 141 +++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 text/0000-blueprints-update.md diff --git a/text/0000-blueprints-update.md b/text/0000-blueprints-update.md new file mode 100644 index 0000000000..2b2b5c5159 --- /dev/null +++ b/text/0000-blueprints-update.md @@ -0,0 +1,141 @@ +- Start Date: 2019-04-17 +- Relevant Team(s): Ember CLI +- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name) +- Tracking: (leave this empty) + +# Syncing Blueprints + +## Summary + +I want to use [ember-cli-update](https://github.com/ember-cli/ember-cli-update) to keep any blueprint up-to-date. Since ember-cli-update can not possibly contain knowledge of all blueprints, some state must be stored in a project. + +## Motivation + +Projects like [libkit](https://github.com/tildeio/libkit), [@glimmer/blueprint](https://github.com/glimmerjs/glimmer.js/tree/master/packages/%40glimmer/blueprint), [@ember/octane-app-blueprint](https://github.com/ember-cli/ember-octane-blueprint), and other app replacement blueprints become out-of-date instantly after generation. Tweaks to the blueprints are only beneficial to newly generated apps. + +## Detailed design + +**State storage schema** + +Up until now, ember-cli-update could update apps without any configuration, but in order to handle all blueprints and their options, some state has to be stored in the project. + +The code is already completed https://github.com/ember-cli/ember-cli-update/pull/552, but I wanted to publish this RFC before releasing it into the wild. I want to make sure the format of these files are agreed upon, because if this is successful, it will probably propagate throughout the ecosystem. + +Where should the state go? + +``` +// .ember-cli +{ + "ember-cli-update": { + "blueprints": [ + { + "name": "my-custom-blueprint", + "version": "0.0.1" + } + ] + } +} +``` + +``` +// ember-cli-update.json +{ + "blueprints": [ + { + "name": "my-custom-blueprint", + "version": "0.0.1" + } + ] +} +``` + +``` +// package.json +{ + // ... + "ember-cli-update": { + "blueprints": [ + { + "name": "my-custom-blueprint", + "version": "0.0.1" + } + ] + } +} +``` + +I vote “ember-cli-update.json”. Since the code will be modified by the updater, it’s easier to reformat JSON. “.ember-cli” I think supports JS, so it would be hard to modify. “package.json” seems like an abuse to put more metadata in there. + +How should the state be structured? + +``` +{ + "blueprints": [ + { + "name": "my-custom-blueprint", + "version": "0.0.1" + } + ] +} +``` + +``` +{ + "blueprints": { + "my-custom-blueprint": { + "version": "0.0.1" + } +} +``` + +Future-proofing for more options + +``` +{ + "additionalFutureOptions": null, + "blueprints": { + "my-custom-blueprint": { + "version": "0.0.1", + "additionalFutureOptions": null, + } + } +} +``` + +**Methods of delivery** + +Blueprints could be responsible for injecting the state into projects + +``` +// my-custom-blueprint/blueprints/my-custom-blueprint/files/.ember-cli +{ + "ember-cli-update": { + "blueprints": [ + { + "name": "my-custom-blueprint", + "version": "<%= blueprintVersion %>" + } + ] + } +} +``` + +or ember-cli-update could manage it itself if the blueprint does not provide this info. You would have to provide the initial blueprint version to start from. + +The goal is for when you type `ember-cli-update` in your project, you will get a prompt like + +``` +$ ember-cli-update +Multiple blueprint updates found, which would you like to update? +* ember-cli +* ember-cli-mirage +* ember-ci +``` + +## How we teach this + +I’m not sure. It could be a section in the ember-cli-update README, or leave it up to the blueprints that want to support this to document. If this feature takes off in the ecosystem, then it might warrant a guides section on keeping your blueprints up-to-date. + +## Drawbacks + +A drawback could be that blueprints start writing this state, but the consumer doesn’t want to use ember-cli-update to keep it in sync. In that case, it’s another file the user has to delete. From 464855635effeda3ea183d9438bbc8e86d99b4b0 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Wed, 17 Apr 2019 16:12:49 +0100 Subject: [PATCH 02/12] add PR link --- text/{0000-blueprints-update.md => 0477-blueprints-update.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename text/{0000-blueprints-update.md => 0477-blueprints-update.md} (97%) diff --git a/text/0000-blueprints-update.md b/text/0477-blueprints-update.md similarity index 97% rename from text/0000-blueprints-update.md rename to text/0477-blueprints-update.md index 2b2b5c5159..647c585622 100644 --- a/text/0000-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -1,6 +1,6 @@ - Start Date: 2019-04-17 - Relevant Team(s): Ember CLI -- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name) +- RFC PR: https://github.com/emberjs/rfcs/pull/477 - Tracking: (leave this empty) # Syncing Blueprints From def064799b985b13a657005a8133826ebc31de1a Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Wed, 17 Apr 2019 16:20:44 +0100 Subject: [PATCH 03/12] add note about private partial blueprints --- text/0477-blueprints-update.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 647c585622..8adc78f7b6 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -132,6 +132,8 @@ Multiple blueprint updates found, which would you like to update? * ember-ci ``` +The reason this is so powerful is any org could create their own _partial_ app blueprint (public or private). This blueprint can make any slight (or massive) tweaks to the official blueprints, and ember-cli-update can keep any app in sync with both the official blueprint and you'r org's blueprints, at the same time. + ## How we teach this I’m not sure. It could be a section in the ember-cli-update README, or leave it up to the blueprints that want to support this to document. If this feature takes off in the ecosystem, then it might warrant a guides section on keeping your blueprints up-to-date. From 29e60fec7033002769111fab165d6765296a8aa0 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Wed, 17 Apr 2019 17:15:37 +0100 Subject: [PATCH 04/12] adding js to code blocks --- text/0477-blueprints-update.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 8adc78f7b6..1548131429 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -23,7 +23,7 @@ The code is already completed https://github.com/ember-cli/ember-cli-update/pull Where should the state go? -``` +```js // .ember-cli { "ember-cli-update": { @@ -37,7 +37,7 @@ Where should the state go? } ``` -``` +```js // ember-cli-update.json { "blueprints": [ @@ -49,7 +49,7 @@ Where should the state go? } ``` -``` +```js // package.json { // ... @@ -68,7 +68,7 @@ I vote “ember-cli-update.json”. Since the code will be modified by the updat How should the state be structured? -``` +```js { "blueprints": [ { @@ -79,7 +79,7 @@ How should the state be structured? } ``` -``` +```js { "blueprints": { "my-custom-blueprint": { @@ -90,7 +90,7 @@ How should the state be structured? Future-proofing for more options -``` +```js { "additionalFutureOptions": null, "blueprints": { @@ -106,7 +106,7 @@ Future-proofing for more options Blueprints could be responsible for injecting the state into projects -``` +```js // my-custom-blueprint/blueprints/my-custom-blueprint/files/.ember-cli { "ember-cli-update": { @@ -127,9 +127,9 @@ The goal is for when you type `ember-cli-update` in your project, you will get a ``` $ ember-cli-update Multiple blueprint updates found, which would you like to update? -* ember-cli -* ember-cli-mirage -* ember-ci + * ember-cli + * ember-cli-mirage + * ember-ci ``` The reason this is so powerful is any org could create their own _partial_ app blueprint (public or private). This blueprint can make any slight (or massive) tweaks to the official blueprints, and ember-cli-update can keep any app in sync with both the official blueprint and you'r org's blueprints, at the same time. From 3d20aa731a1c3362add8310739560656f364b5ce Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Wed, 17 Apr 2019 17:18:17 +0100 Subject: [PATCH 05/12] fix wording --- text/0477-blueprints-update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 1548131429..66ca87dfa6 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -132,7 +132,7 @@ Multiple blueprint updates found, which would you like to update? * ember-ci ``` -The reason this is so powerful is any org could create their own _partial_ app blueprint (public or private). This blueprint can make any slight (or massive) tweaks to the official blueprints, and ember-cli-update can keep any app in sync with both the official blueprint and you'r org's blueprints, at the same time. +The reason this is so powerful is any org could create their own _partial_ project blueprint (public or private). This blueprint can make any slight (or massive) tweaks to the official blueprints, and ember-cli-update can keep any project in sync with both the official blueprint and your org's blueprints, at the same time. ## How we teach this From 71f1ffca6f83febba432bd4c8bacba2200a7c507 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Mon, 22 Apr 2019 10:32:58 +0100 Subject: [PATCH 06/12] add notes about ember-cli-update.json --- text/0477-blueprints-update.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 66ca87dfa6..04dc6cefae 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -66,6 +66,8 @@ Where should the state go? I vote “ember-cli-update.json”. Since the code will be modified by the updater, it’s easier to reformat JSON. “.ember-cli” I think supports JS, so it would be hard to modify. “package.json” seems like an abuse to put more metadata in there. +I've found via further testing that mixing a file that is tracked by the default ember-cli blueprint (.ember-cli, package.json) and modified by ember-cli-update (to update the blueprint metadata), it gets cumbersome. Both processes try to edit the same file. So in theory, ember-cli could alter the .ember-cli file in a way that conflicts with what you have in yours. This would give you a git conflict, then the updater can't read it anymore because it is in a state of invalid JS. I think this further supports a separate file. + How should the state be structured? ```js From 401d2aa687b3470cf57cda9c1623553d00218389 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Mon, 22 Apr 2019 10:42:47 +0100 Subject: [PATCH 07/12] add section about partials --- text/0477-blueprints-update.md | 48 ++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 04dc6cefae..8f84fa9ae8 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -136,6 +136,54 @@ Multiple blueprint updates found, which would you like to update? The reason this is so powerful is any org could create their own _partial_ project blueprint (public or private). This blueprint can make any slight (or massive) tweaks to the official blueprints, and ember-cli-update can keep any project in sync with both the official blueprint and your org's blueprints, at the same time. +**Complete vs partial** + +We need a way to denote a project replacement blueprint and a supplemental blueprint. A project replacement removes any sort of default ember-cli blueprint tracking, even if it still looks like a normal Ember project (has ember-cli, ember-addon, etc.). A supplemental blueprint is one that piggy-backs on a complete blueprint and makes certain tweaks to files. Think of ember-cli-mirage's extra project configs, or your company's custom settings on top of a normal Ember app. + +```js +{ + "blueprints": { + "my-app-blueprint": { + "version": "0.0.1" + }, + "my-addon-blueprint": { + "version": "0.0.1", + "isPartial": true + } + } +} +``` + +``` +$ ember-cli-update +Multiple blueprint updates found, which would you like to update? + * my-app-blueprint + * my-addon-blueprint +``` + +```js +{ + "blueprints": { + "my-app-blueprint": { + "version": "0.0.1", + "isPartial": true + }, + "my-addon-blueprint": { + "version": "0.0.1", + "isPartial": true + } + } +} +``` + +``` +$ ember-cli-update +Multiple blueprint updates found, which would you like to update? + * ember-cli + * my-app-blueprint + * my-addon-blueprint +``` + ## How we teach this I’m not sure. It could be a section in the ember-cli-update README, or leave it up to the blueprints that want to support this to document. If this feature takes off in the ecosystem, then it might warrant a guides section on keeping your blueprints up-to-date. From ccadff5cc117f98d174989b179479cb3d82e0fe9 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Mon, 22 Apr 2019 11:06:25 +0100 Subject: [PATCH 08/12] add section about options --- text/0477-blueprints-update.md | 40 ++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 8f84fa9ae8..69577b9a82 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -86,6 +86,7 @@ How should the state be structured? "blueprints": { "my-custom-blueprint": { "version": "0.0.1" + } } } ``` @@ -184,6 +185,45 @@ Multiple blueprint updates found, which would you like to update? * my-addon-blueprint ``` +**Preserving options** + +I'm not sure if anyone does it now, but it could be possible to handle options when generating a new project via a custom blueprints. + +``` +ember new my-app -b my-blueprint --option1 --option2=foo +``` + +```js +// my-blueprint/files/ember-cli-update.json +{ + "blueprints": [ + { + "name": "my-blueprint", + "version": "<%= blueprintVersion %>", + "options": ["option0=<%= option0 %>", "option1=<%= option1 %>", "option2=\"<%= option2 %>\""] + } + ] +} +``` + +```js +// my-app/ember-cli-update.json +{ + "blueprints": { + "my-blueprint": { + "version": "0.0.1", + "options": ["option0=false", "option1=true", "option2=\"foo\""] + } + } +} +``` + +The updater can now generate a project with the correct options. + +``` +ember new my-app -b my-blueprint --option0=false --option1=true --option2="foo" +``` + ## How we teach this I’m not sure. It could be a section in the ember-cli-update README, or leave it up to the blueprints that want to support this to document. If this feature takes off in the ecosystem, then it might warrant a guides section on keeping your blueprints up-to-date. From 884bfe991c1bd6bea434ba3b30fc83b6fa594ef9 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Mon, 22 Apr 2019 11:11:42 +0100 Subject: [PATCH 09/12] add codemods section --- text/0477-blueprints-update.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 69577b9a82..31e49d5199 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -224,6 +224,21 @@ The updater can now generate a project with the correct options. ember new my-app -b my-blueprint --option0=false --option1=true --option2="foo" ``` +**Codemods** + +There is no reason why you couldn't provide your own codemods with this system. This would be especially useful for project replacement blueprints. We would use the existing codemod system with version detection, option detection, etc. + +```js +{ + "blueprints": { + "my-blueprint": { + "version": "0.0.1", + "codemods": "some-server.com/my-blueprint-codemods-manifest.json" + } + } +} +``` + ## How we teach this I’m not sure. It could be a section in the ember-cli-update README, or leave it up to the blueprints that want to support this to document. If this feature takes off in the ecosystem, then it might warrant a guides section on keeping your blueprints up-to-date. From 2a0c5c3bd0b31e37abc5dc750222656417aeb929 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Sun, 1 Sep 2019 12:42:24 +0100 Subject: [PATCH 10/12] standardize on ember-cli-update.json --- text/0477-blueprints-update.md | 135 ++++++++------------------------- 1 file changed, 30 insertions(+), 105 deletions(-) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 31e49d5199..c03d131bb3 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -19,26 +19,10 @@ Projects like [libkit](https://github.com/tildeio/libkit), [@glimmer/blueprint]( Up until now, ember-cli-update could update apps without any configuration, but in order to handle all blueprints and their options, some state has to be stored in the project. -The code is already completed https://github.com/ember-cli/ember-cli-update/pull/552, but I wanted to publish this RFC before releasing it into the wild. I want to make sure the format of these files are agreed upon, because if this is successful, it will probably propagate throughout the ecosystem. +The code is already completed [here](https://github.com/ember-cli/ember-cli-update/pull/552), but I wanted to publish this RFC before releasing it into the wild. I want to make sure the format of these files are agreed upon, because if this is successful, it will probably propagate throughout the ecosystem. -Where should the state go? - -```js -// .ember-cli -{ - "ember-cli-update": { - "blueprints": [ - { - "name": "my-custom-blueprint", - "version": "0.0.1" - } - ] - } -} -``` - -```js -// ember-cli-update.json +```json +// config/ember-cli-update.json { "blueprints": [ { @@ -49,28 +33,11 @@ Where should the state go? } ``` -```js -// package.json -{ - // ... - "ember-cli-update": { - "blueprints": [ - { - "name": "my-custom-blueprint", - "version": "0.0.1" - } - ] - } -} -``` - -I vote “ember-cli-update.json”. Since the code will be modified by the updater, it’s easier to reformat JSON. “.ember-cli” I think supports JS, so it would be hard to modify. “package.json” seems like an abuse to put more metadata in there. - -I've found via further testing that mixing a file that is tracked by the default ember-cli blueprint (.ember-cli, package.json) and modified by ember-cli-update (to update the blueprint metadata), it gets cumbersome. Both processes try to edit the same file. So in theory, ember-cli could alter the .ember-cli file in a way that conflicts with what you have in yours. This would give you a git conflict, then the updater can't read it anymore because it is in a state of invalid JS. I think this further supports a separate file. +`ember-cli-update.json` will be rewritten by the tool, which is why JSON is preferred over JS. How should the state be structured? -```js +```json { "blueprints": [ { @@ -81,7 +48,7 @@ How should the state be structured? } ``` -```js +```json { "blueprints": { "my-custom-blueprint": { @@ -93,7 +60,7 @@ How should the state be structured? Future-proofing for more options -```js +```json { "additionalFutureOptions": null, "blueprints": { @@ -109,17 +76,15 @@ Future-proofing for more options Blueprints could be responsible for injecting the state into projects -```js -// my-custom-blueprint/blueprints/my-custom-blueprint/files/.ember-cli +```json +// my-custom-blueprint/blueprints/my-custom-blueprint/files/config/ember-cli-update.json { - "ember-cli-update": { - "blueprints": [ - { - "name": "my-custom-blueprint", - "version": "<%= blueprintVersion %>" - } - ] - } + "blueprints": [ + { + "name": "my-custom-blueprint", + "version": "<%= blueprintVersion %>" + } + ] } ``` @@ -137,54 +102,6 @@ Multiple blueprint updates found, which would you like to update? The reason this is so powerful is any org could create their own _partial_ project blueprint (public or private). This blueprint can make any slight (or massive) tweaks to the official blueprints, and ember-cli-update can keep any project in sync with both the official blueprint and your org's blueprints, at the same time. -**Complete vs partial** - -We need a way to denote a project replacement blueprint and a supplemental blueprint. A project replacement removes any sort of default ember-cli blueprint tracking, even if it still looks like a normal Ember project (has ember-cli, ember-addon, etc.). A supplemental blueprint is one that piggy-backs on a complete blueprint and makes certain tweaks to files. Think of ember-cli-mirage's extra project configs, or your company's custom settings on top of a normal Ember app. - -```js -{ - "blueprints": { - "my-app-blueprint": { - "version": "0.0.1" - }, - "my-addon-blueprint": { - "version": "0.0.1", - "isPartial": true - } - } -} -``` - -``` -$ ember-cli-update -Multiple blueprint updates found, which would you like to update? - * my-app-blueprint - * my-addon-blueprint -``` - -```js -{ - "blueprints": { - "my-app-blueprint": { - "version": "0.0.1", - "isPartial": true - }, - "my-addon-blueprint": { - "version": "0.0.1", - "isPartial": true - } - } -} -``` - -``` -$ ember-cli-update -Multiple blueprint updates found, which would you like to update? - * ember-cli - * my-app-blueprint - * my-addon-blueprint -``` - **Preserving options** I'm not sure if anyone does it now, but it could be possible to handle options when generating a new project via a custom blueprints. @@ -193,26 +110,34 @@ I'm not sure if anyone does it now, but it could be possible to handle options w ember new my-app -b my-blueprint --option1 --option2=foo ``` -```js -// my-blueprint/files/ember-cli-update.json +```json +// my-blueprint/files/config/ember-cli-update.json { "blueprints": [ { "name": "my-blueprint", "version": "<%= blueprintVersion %>", - "options": ["option0=<%= option0 %>", "option1=<%= option1 %>", "option2=\"<%= option2 %>\""] + "options": [ + "option0=<%= option0 %>", + "option1=<%= option1 %>", + "option2=\"<%= option2 %>\"" + ] } ] } ``` -```js -// my-app/ember-cli-update.json +```json +// my-app/config/ember-cli-update.json { "blueprints": { "my-blueprint": { "version": "0.0.1", - "options": ["option0=false", "option1=true", "option2=\"foo\""] + "options": [ + "option0=false", + "option1=true", + "option2=\"foo\"" + ] } } } @@ -228,7 +153,7 @@ ember new my-app -b my-blueprint --option0=false --option1=true --option2="foo" There is no reason why you couldn't provide your own codemods with this system. This would be especially useful for project replacement blueprints. We would use the existing codemod system with version detection, option detection, etc. -```js +```json { "blueprints": { "my-blueprint": { From 19b1a4feece5b2e8184073d0ab39a5ab0f5e2613 Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Thu, 5 Sep 2019 20:15:06 +0100 Subject: [PATCH 11/12] added more command ideas and codemod options --- text/0477-blueprints-update.md | 57 ++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index c03d131bb3..0ffd0b68b0 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -72,6 +72,43 @@ Future-proofing for more options } ``` +**Commands** + +***bootstrap*** + +``` +ember-cli-update bootstrap +``` + +This starts an `ember-cli-update.json` file for you with the detected ember-cli blueprint version. It uses the same logic we currently have for detecting the ember-cli blueprint version, but now since the state is stored, we don't have to run the detection logic anymore. + +***init*** + +``` +ember-cli-update init +ember-cli-update init -b libkit +ember-cli-update init -b my-custom-blueprint --custom-option-1 --custom-option-2 foo +``` + +This is similar to `ember init` or `ember-cli-update --reset`, but also stores the blueprint information in `ember-cli-update.json`. It also stores any options used to create future update diffs. + +***install*** + +``` +ember-cli-update install ember-cli-mirage +``` + +This is the same as `ember install ember-cli-mirage` except that it stores the blueprint state for later updating. + +***save*** + +``` +ember-cli-update save libkit --from 0.5.18 +ember-cli-update save ember-cli-mirage --from 0.4.0 +``` + +This is a helper for saving the state of an old blueprint's run without ember-cli-update. The usefulness of this is questionable, because you have to remember something you did in the past. Its only usefulness is getting a project set up without having to know the `ember-cli-update.json` schema. + **Methods of delivery** Blueprints could be responsible for injecting the state into projects @@ -164,6 +201,26 @@ There is no reason why you couldn't provide your own codemods with this system. } ``` +TODO: The options need to be normalized somehow to be used in the codemods system. + +`--custom-option foo` vs `--custom-option=foo` vs `--custom-option="foo"` + +```js +// This would probably be bad as `foo` would be treated as an option +"options": [ + "--custom-option", + "foo" +] +// This is better +"options": [ + "--custom-option=\"foo\"" +] +// or maybe this? +"options": [ + "customOption=\"foo\"" +] +``` + ## How we teach this I’m not sure. It could be a section in the ember-cli-update README, or leave it up to the blueprints that want to support this to document. If this feature takes off in the ecosystem, then it might warrant a guides section on keeping your blueprints up-to-date. From 9d9b1cac40c9a34109c5b9a62600542e9f1c6f5c Mon Sep 17 00:00:00 2001 From: Kelly Selden Date: Sun, 8 Dec 2019 17:04:53 +0000 Subject: [PATCH 12/12] add the latest config schema --- text/0477-blueprints-update.md | 202 ++++++++++++++++++--------------- 1 file changed, 112 insertions(+), 90 deletions(-) diff --git a/text/0477-blueprints-update.md b/text/0477-blueprints-update.md index 0ffd0b68b0..460c015d8e 100644 --- a/text/0477-blueprints-update.md +++ b/text/0477-blueprints-update.md @@ -19,15 +19,20 @@ Projects like [libkit](https://github.com/tildeio/libkit), [@glimmer/blueprint]( Up until now, ember-cli-update could update apps without any configuration, but in order to handle all blueprints and their options, some state has to be stored in the project. -The code is already completed [here](https://github.com/ember-cli/ember-cli-update/pull/552), but I wanted to publish this RFC before releasing it into the wild. I want to make sure the format of these files are agreed upon, because if this is successful, it will probably propagate throughout the ecosystem. +The code is already completed but opt-in. I wanted to publish this RFC before releasing it into the wild. I want to make sure the format of these files are agreed upon, because if this is successful, it will probably propagate throughout the ecosystem. ```json // config/ember-cli-update.json { - "blueprints": [ + "packages": [ { "name": "my-custom-blueprint", - "version": "0.0.1" + "version": "0.0.1", + "blueprints": [ + { + "name": "my-custom-blueprint" + } + ] } ] } @@ -37,38 +42,77 @@ The code is already completed [here](https://github.com/ember-cli/ember-cli-upda How should the state be structured? -```json -{ - "blueprints": [ - { - "name": "my-custom-blueprint", - "version": "0.0.1" - } - ] -} -``` - -```json -{ - "blueprints": { - "my-custom-blueprint": { - "version": "0.0.1" - } - } -} -``` - -Future-proofing for more options - -```json -{ - "additionalFutureOptions": null, - "blueprints": { - "my-custom-blueprint": { - "version": "0.0.1", - "additionalFutureOptions": null, - } - } +```ts +/** + This lives at config/ember-cli-update.json by default. +*/ +interface BlueprintConfig { + /** + Keep track of incompatible schema changes. + */ + schemaVersion: number; + + /** + A package is a collection of blueprints from a single source. + */ + packages: { + /** + The name of the package. + */ + name: string; + + /** + Target a blueprint on your local filesystem, monorepo or otherwise. + */ + location?: string; + + /** + The version of the package used for blueprint diffing. + */ + version: string; + + /** + The blueprints in the package. Can be a default blueprint having + the same name as the package, or a named blueprint like component + generators. + */ + blueprints: { + /** + A base blueprint is the blueprint you started your project with. + This could be the ember app blueprint, or a custom blueprint like libkit. + If this is missing or false, it is a partial blueprint, like the changes + you get when installing an ember addon like ember-cli-mirage. + There must be one base blueprint at all times. + */ + isBaseBlueprint?: boolean; + + /** + The name of the blueprint to be run. + */ + name: string; + + /** + The path inside your project to run in. Think deeply nested + component generators. Missing means project root. + */ + cwd?: string; + + /** + The location of a codemods manifest if there are codemods + associated with this blueprint. + */ + codemodsUrl?: string; + + /** + All options should be normalized to match any codemod requirements. + The work to normalise them might not be done at first, so users + writing the CLI commands are expected to do it. For example, + `--no-welcome` should be expanded to `--welcome=false` so that + a codemod with a requirement of `[ "--welcome=false" ]` can match it. + */ + options?: string[]; + }[] + }[] } ``` @@ -111,22 +155,6 @@ This is a helper for saving the state of an old blueprint's run without ember-cl **Methods of delivery** -Blueprints could be responsible for injecting the state into projects - -```json -// my-custom-blueprint/blueprints/my-custom-blueprint/files/config/ember-cli-update.json -{ - "blueprints": [ - { - "name": "my-custom-blueprint", - "version": "<%= blueprintVersion %>" - } - ] -} -``` - -or ember-cli-update could manage it itself if the blueprint does not provide this info. You would have to provide the initial blueprint version to start from. - The goal is for when you type `ember-cli-update` in your project, you will get a prompt like ``` @@ -148,60 +176,60 @@ ember new my-app -b my-blueprint --option1 --option2=foo ``` ```json -// my-blueprint/files/config/ember-cli-update.json +// my-app/config/ember-cli-update.json { - "blueprints": [ + "packages": [ { "name": "my-blueprint", - "version": "<%= blueprintVersion %>", - "options": [ - "option0=<%= option0 %>", - "option1=<%= option1 %>", - "option2=\"<%= option2 %>\"" - ] - } - ] -} -``` - -```json -// my-app/config/ember-cli-update.json -{ - "blueprints": { - "my-blueprint": { "version": "0.0.1", - "options": [ - "option0=false", - "option1=true", - "option2=\"foo\"" + "blueprints": [ + { + "name": "my-blueprint", + "options": [ + "option1=true", + "option2=\"foo\"" + ] + } ] } - } + ] } ``` The updater can now generate a project with the correct options. -``` -ember new my-app -b my-blueprint --option0=false --option1=true --option2="foo" -``` - **Codemods** There is no reason why you couldn't provide your own codemods with this system. This would be especially useful for project replacement blueprints. We would use the existing codemod system with version detection, option detection, etc. ```json { - "blueprints": { - "my-blueprint": { + "packages": [ + { + "name": "my-blueprint", "version": "0.0.1", - "codemods": "some-server.com/my-blueprint-codemods-manifest.json" + "blueprints": [ + { + "name": "my-blueprint", + "codemodsUrl": "some-server.com/my-blueprint-codemods-manifest.json" + } + ] } - } + ] } ``` -TODO: The options need to be normalized somehow to be used in the codemods system. +## How we teach this + +I’m not sure. It could be a section in the ember-cli-update README, or leave it up to the blueprints that want to support this to document. If this feature takes off in the ecosystem, then it might warrant a guides section on keeping your blueprints up-to-date. + +## Drawbacks + +A drawback could be that blueprints start writing this state, but the consumer doesn’t want to use ember-cli-update to keep it in sync. In that case, it’s another file the user has to delete. + +## Unresolved questions + +The options need to be normalized somehow to be used in the codemods system. `--custom-option foo` vs `--custom-option=foo` vs `--custom-option="foo"` @@ -221,10 +249,4 @@ TODO: The options need to be normalized somehow to be used in the codemods syste ] ``` -## How we teach this - -I’m not sure. It could be a section in the ember-cli-update README, or leave it up to the blueprints that want to support this to document. If this feature takes off in the ecosystem, then it might warrant a guides section on keeping your blueprints up-to-date. - -## Drawbacks - -A drawback could be that blueprints start writing this state, but the consumer doesn’t want to use ember-cli-update to keep it in sync. In that case, it’s another file the user has to delete. +For now, we should leave it up to the end-user to normalize the options to match any codemod manifest. This is too hard a problem to nail down on the first iteration.