ENDOC-534 export-publish tutorial #586

jyunmitch · 2022-10-05T15:33:18Z

No description provided.

jyunmitch · 2022-10-05T15:35:32Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

@@ -48,8 +43,8 @@ kubectl describe ingress/default-sso-in-namespace-ingress -n entando
 10. Click `Add Selected` to add `superuser` to the `Assigned Roles`. This change will be saved automatically. 
 11. Go to the `Credentials` tab and copy the `Secret` shown there for use in the next section

-### Create env.json
-1. Create a directory where you'll run the bundler and go to that directory:
+### Create the `env.json`


@nshaw, is there a general term for env.json type files? Bundle Environment config file? Environment config file for Bundle?

If there isn't a good alternative, I'll leave it as is.

-> Create the env.json configuration file

jyunmitch · 2022-10-05T15:37:39Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+ent bundle init YOUR-BUNDLE-NAME
+cd YOUR-BUNDLE-NAME
+```
+2. Copy the resources from the bundle directory, with the exception of microservices (/plugins) and micro frontends (/widgets), to the `platform` directory:


this section may be better to change into just text, without the cp command.

I'm on the fence here. I provided a more general command but describing the process might actually be good enough. One nuance is that the widgets can contain non-MFE widgets, like in our basic tutorial. We probably need to clarify that the /plugins and /widgets will need to be handled manually because of things like that. You have a good start on that below.

is the file path used for the cp set in stone?

nshaw · 2022-10-05T18:13:56Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+```
+2. Copy the resources from the bundle directory, with the exception of microservices (/plugins) and micro frontends (/widgets), to the `platform` directory:
+```
+cp -R ../testBundle/bundle/assets platform/


I think we can generalize this so it's done in one step. cp -R ../testBundle/bundle/* platform/

but it will copy over the descriptor.yaml, the widget & plugin directories. Is that ok?

Might be better to just describe the steps. We could do a find command like I did for the jhipster tutorial but it feels like overkill somehow.

nshaw · 2022-10-05T18:14:25Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+```
+cp -R ../testBundle/bundle/assets platform/
+```
+Repeat for all the other components in your bundle, including assets, contentModels, contents, fragments, labels, pageModels, resources, categories, contentTypes, groups, languages, and pages.


With the general cp you won't need to have this repeat sentence.

nshaw · 2022-10-05T19:19:58Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+ent bundle init YOUR-BUNDLE-NAME
+cd YOUR-BUNDLE-NAME
+```
+2. Copy the resources from the bundle directory, with the exception of microservices (/plugins) and micro frontends (/widgets), to the `platform` directory:


I'm on the fence here. I provided a more general command but describing the process might actually be good enough. One nuance is that the widgets can contain non-MFE widgets, like in our basic tutorial. We probably need to clarify that the /plugins and /widgets will need to be handled manually because of things like that. You have a good start on that below.

nshaw · 2022-10-05T19:20:32Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

@@ -48,8 +43,8 @@ kubectl describe ingress/default-sso-in-namespace-ingress -n entando
 10. Click `Add Selected` to add `superuser` to the `Assigned Roles`. This change will be saved automatically. 
 11. Go to the `Credentials` tab and copy the `Secret` shown there for use in the next section

-### Create env.json
-1. Create a directory where you'll run the bundler and go to that directory:
+### Create the `env.json`


-> Create the env.json configuration file

jyunmitch · 2022-10-05T19:30:16Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+:::
+
+### Construct the Docker-based Bundle Structure
+


@Lyd1aCla1r3, skip this section for now, lines 84 to the end, it is going to get reworked

Lyd1aCla1r3 · 2022-10-05T18:26:21Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md


 ``` 
 $ ls bundle
 assets      contentModels  contents         fragments  labels     pageModels  resources
 categories  contentTypes   descriptor.yaml  groups     languages  pages       widgets
 ```

-You now have a complete Entando project structure! You can inspect the output to edit the exported components or deploy it to another Entando Application.
+You now have a complete Entando project structure for a git-based bundle! You can inspect the output to edit the exported components or [deploy](publish-project-bundle.md) it to another Entando Application. 


is it required that you deploy to a different bundle? or is any instance fair game, including the application used for the export?

not sure what you mean. it was just exported from another location, so you are installing it for the first time in this local instance or to any instance. Why would you install it back to where you just exported from, it would be making work for no reason.

maybe i'm misunderstanding the use case. @nshaw if you have a bundle with some good stuff in it and want a similar, slightly different bundle in the same application, could/should you use the export command instead of locally cloning the files and doing surgery on what you want to keep/toss? if this is a possibility i suggest we remove the word "another"

Lyd1aCla1r3 · 2022-10-05T20:01:04Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+```
+cp -R ../testBundle/bundle/assets platform/
+```
+Repeat for all the other components in your bundle, including assets, contentModels, contents, fragments, labels, pageModels, resources, categories, contentTypes, groups, languages, and pages.


"Repeat for" sounds a little abbreviated and like shorthand here; "Repeat this process / these steps, etc." is a bit more fleshed out

Lyd1aCla1r3 · 2022-10-05T20:01:17Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+ent bundle init YOUR-BUNDLE-NAME
+cd YOUR-BUNDLE-NAME
+```
+2. Copy the resources from the bundle directory, with the exception of microservices (/plugins) and micro frontends (/widgets), to the `platform` directory:


is the file path used for the cp set in stone?

Lyd1aCla1r3 · 2022-10-05T20:03:40Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+
+If there are micro frontends or microservices in the bundle, use the source code to migrate them to their designated folders. Use the [ent bundle CLI tool](../../../docs/getting-started/ent-bundle.md) to assist in the process. Also check out the [Entando Bundle details](../../../docs/curate/bundle-details.md) page to define specific attributes for the MFEs and MSs in the bundle descriptor, `entando.json`.
+
+3. With the project structure in place, [build and publish](publish-project-bundle.md) your bundle.


build and publish -> build and deploy (our usual phrasing when referring to this process and a bit more representative of what's occurring)

the tutorial is called build and publish. And I don't think we need to call it the same exact thing every time unless it is a name of a thing

in general i agree, but deploy is a more appropriate word imo. the end goal isn't to publish things to git/docker

Lyd1aCla1r3 · 2022-10-05T20:10:52Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+```
+Repeat for all the other components in your bundle, including assets, contentModels, contents, fragments, labels, pageModels, resources, categories, contentTypes, groups, languages, and pages.
+
+If there are micro frontends or microservices in the bundle, use the source code to migrate them to their designated folders. Use the [ent bundle CLI tool](../../../docs/getting-started/ent-bundle.md) to assist in the process. Also check out the [Entando Bundle details](../../../docs/curate/bundle-details.md) page to define specific attributes for the MFEs and MSs in the bundle descriptor, `entando.json`.


the use of the source code here needs some clarification... do you make use of the source code when migrating, e.g. move the source code, or do you use the source code as in execute it? i think it's the former...

@nshaw i feel like there was a decision regarding the use of the word "migration" - that it should be used exclusively wrt changing platforms?

did we introduce MS as an acronym here? MSs looks really odd and is not a universally adopted initialism. even a somewhat exhaustive google search doesn't yield microservice as a candidate

1 & 2 edited a bit but it's intentionally vague and I think there are many ways to do it. No nothing to execute

Can we discuss about MSs later. After 7.1 is mostly done. changed here anyway

vague is fine (no details necessary), but it's not clear how to read it and that's a bit different

sure. i remember at one point we were explicitly defining uncommon acronyms before we used them. in this case it should be pretty obv what MS stands for given the context

vague is not the right word in this context, it's broad. And it needs to be because there are many ways of doing the same thing which is totally implied. I don't think that is unclear.

"1 & 2 edited a bit but it's intentionally vague"

there may be many ways to do the same thing but that's beside the point here. this clearly reads like you run source code to perform a migration.

Lyd1aCla1r3 · 2022-10-05T20:21:02Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md


-This command generates the same bundle directory structure as an Entando project, including a bundle descriptor file.
+This tutorial illustrates how to use the ent bundler to export a git-based Entando Bundle. This package can be deployed to a running Entando instance or modified to a docker-based bundle to take advantage of Entando's latest composable methods. The procedure assumes you're using an Entando quickstart application. Otherwise, you may need to adjust specific URLs, credentials, namespaces, etc., for a custom application.


"illustrates" is a bit inaccurate because there are no graphics or even a start-to-finish working example. describes?

"modified to" sounds odd; "converted to"

"Entando's latest composable methods" doesn't seem to fit. if that were the case, we should list them explicitly instead of with a vague reference; however, most of the benefits/changes consequent to the restructuring (for example, what alessandro listed in his demo slide) cannot be considered methods.

can simplify the second sentence to close the distance between the subject and verb and avoid the pause of the last comma: "To use a custom application, you may need to..."

edited

Nathan thought converted was not quite right

Disagree, the ent bundle pack, publish, deploy as a whole is a method. there are several layers to this process, so it can be considered methods. Is there something specific about methods that we have to list.

Don't want to mess with the last two sentences, not sure why it's there to begin with in this situation and not others, but no time to investigate and fix. Too much other work and this seems minor

modified is a great word choice, but you don't modify to something. modify to show/say/do etc., but modify to a state, not a thing. for example, modify to be a docker-based bundle works, albeit inelegantly

disagree... "modified to a docker-based bundle to take advantage of Entando's latest composable methods" is too vague to provide much value to the reader; also, there are several significant advantages to docker-based bundles, and this wording doesn't communicate that / limits and undersells the new structure and process. and i think we should be somewhat aware of using "methods" as a word choice, given someone versed in software will associate that word with "a programmed procedure that is defined as part of a class and included in any object of that class" and perhaps make some false assumptions. but generally speaking, pack+publish+deploy is how you create a bundle, and it's pretty much the only way to do it. whether the bundle is docker- or git-based, and regardless of what commands/tools are used.

i was only suggesting a quick edit to move a couple words

edited the modified part

let's discuss the use of "methods". For now, don't agree on the narrow definition of methods. in this context it is clearly not calling for some specific program parameter. pretty sure we've used the term composable methods before

@nshaw please weigh in on 3

@nshaw we synced offline

@nshaw jinah is referring to component decoupling, e.g. the ability to execute commands on only MFEs (and vice versa)

Lyd1aCla1r3 · 2022-10-05T20:30:04Z

vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md

+The ent bundler command can export a bundle from an existing Entando Application to be utilized in the following ways: 
+- For the initial install of components into an Entando Application
+- To migrate bundles from one environment to another (e.g. Dev to QA)
+- To provide a template for building a new application


this block is kind of unnecessarily wordy; can be simplified, especially because i think the command exports a bundle by definition, not optionally.
"The ent bundler command exports a bundle from an existing Entando Application to:

Perform the initial install of components into an Entando Application

Migrate bundles from one environment to another (e.g. Dev to QA)

Provide a template for building a new application"

ENDOC-534 export-publish tutorial

54e9100

jyunmitch requested review from nshaw and Lyd1aCla1r3 October 5, 2022 15:33

jyunmitch commented Oct 5, 2022

View reviewed changes

nshaw reviewed Oct 5, 2022

View reviewed changes

jyunmitch commented Oct 5, 2022

View reviewed changes

Lyd1aCla1r3 reviewed Oct 5, 2022

View reviewed changes

ENDOC-534 language edit

fbfeda2

Lyd1aCla1r3 self-requested a review October 6, 2022 19:05

Lyd1aCla1r3 approved these changes Oct 6, 2022

View reviewed changes

ENDOC-534 refining edits

f384a03

jyunmitch merged commit 29bbf54 into main Oct 6, 2022

jyunmitch deleted the ENDOC-534 branch October 6, 2022 19:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENDOC-534 export-publish tutorial #586

ENDOC-534 export-publish tutorial #586

jyunmitch commented Oct 5, 2022

jyunmitch Oct 5, 2022 •

edited

Loading

nshaw Oct 5, 2022

jyunmitch Oct 5, 2022

nshaw Oct 5, 2022

Lyd1aCla1r3 Oct 5, 2022

nshaw Oct 5, 2022

jyunmitch Oct 5, 2022

nshaw Oct 5, 2022

nshaw Oct 5, 2022

nshaw Oct 5, 2022

nshaw Oct 5, 2022

jyunmitch Oct 5, 2022

Lyd1aCla1r3 Oct 5, 2022

jyunmitch Oct 5, 2022

Lyd1aCla1r3 Oct 6, 2022

Lyd1aCla1r3 Oct 5, 2022

Lyd1aCla1r3 Oct 5, 2022

Lyd1aCla1r3 Oct 5, 2022

jyunmitch Oct 5, 2022

Lyd1aCla1r3 Oct 6, 2022

Lyd1aCla1r3 Oct 5, 2022

jyunmitch Oct 5, 2022 •

edited

Loading

Lyd1aCla1r3 Oct 6, 2022

jyunmitch Oct 6, 2022 •

edited

Loading

Lyd1aCla1r3 Oct 6, 2022

Lyd1aCla1r3 Oct 5, 2022

jyunmitch Oct 5, 2022

Lyd1aCla1r3 Oct 6, 2022

jyunmitch Oct 6, 2022 •

edited

Loading

Lyd1aCla1r3 Oct 6, 2022

Lyd1aCla1r3 Oct 6, 2022

Lyd1aCla1r3 Oct 6, 2022

Lyd1aCla1r3 Oct 5, 2022


		If there are micro frontends or microservices in the bundle, use the source code to migrate them to their designated folders. Use the [ent bundle CLI tool](../../../docs/getting-started/ent-bundle.md) to assist in the process. Also check out the [Entando Bundle details](../../../docs/curate/bundle-details.md) page to define specific attributes for the MFEs and MSs in the bundle descriptor, `entando.json`.

		3. With the project structure in place, [build and publish](publish-project-bundle.md) your bundle.


		This command generates the same bundle directory structure as an Entando project, including a bundle descriptor file.
		This tutorial illustrates how to use the ent bundler to export a git-based Entando Bundle. This package can be deployed to a running Entando instance or modified to a docker-based bundle to take advantage of Entando's latest composable methods. The procedure assumes you're using an Entando quickstart application. Otherwise, you may need to adjust specific URLs, credentials, namespaces, etc., for a custom application.

ENDOC-534 export-publish tutorial #586

ENDOC-534 export-publish tutorial #586

Conversation

jyunmitch commented Oct 5, 2022

jyunmitch Oct 5, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyunmitch Oct 5, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyunmitch Oct 6, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyunmitch Oct 6, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jyunmitch Oct 5, 2022 •

edited

Loading

jyunmitch Oct 5, 2022 •

edited

Loading

jyunmitch Oct 6, 2022 •

edited

Loading

jyunmitch Oct 6, 2022 •

edited

Loading