ENDOC-565 first pass #574

jyunmitch · 2022-09-19T21:02:15Z

No description provided.

vuepress/docs/next/docs/curate/bundle-component-details.md

nshaw · 2022-09-20T01:22:21Z

vuepress/docs/next/docs/curate/bundle-component-details.md

+# Bundle Component Descriptors 
+
+
+Elements such as simple widgets, page templates, groups, and static resources are classified as platform components on Entando. This page describes each of these elements with an example.


I might switch to "simple widgets, fragments, pages, content, and static resources". Pages and content are the most common types for sure so maybe even lead with them.

vuepress/docs/next/docs/curate/bundle-component-details.md

nshaw · 2022-09-20T01:27:03Z

vuepress/docs/next/docs/curate/bundle-versions-faq.md

-1. You can edit the bundle directly using the command `kubectl edit entandodebundles.entando.org -n <namespace-of-the-bundle> <name-of-the-bundle>`
+- 1.0
+- v0.1.0-alpha
+- 1.0.1-SNAPSHOT


Remove line 49 and 50. Those are not valid in the current semantic versioning we use which is only x.y.z and vx,y,z,

vuepress/docs/next/docs/curate/bundle-versions-faq.md

nshaw · 2022-09-20T01:28:35Z

vuepress/docs/next/docs/curate/bundle-component-details.md

+
+
+<!--
+## Static Resources


I think we should activate once we get an answer on the direction, hopefully tomorrow. Or make sure we have a note on it and plan to do it once the code is available to test. That could be safer I suppose.

vuepress/docs/next/docs/curate/bundle-component-details.md

Lyd1aCla1r3 · 2022-09-20T05:03:30Z

vuepress/docs/next/docs/curate/bundle-component-details.md

+```
+>Note: Older names `pageModels` and `contentModels` for `pageTemplates` and `contentTemplates` respectively are still supported on Entando 7.1. 
+
+## Widgets 


in the widget, fragments and page templates code: capitalization is really inconsistent. minor because annoying, not confusing, but still looks careless. much better impression to fix it.

I think you are referring to 'code' in the descriptors?? Or are you talking about the name. The 'code' allows caps.

i meant the content under those headers; capitalization in the descriptions is all over the place

I changed the most blatant one, otherwise none of those capitalizations are format issues.

Lyd1aCla1r3 · 2022-09-20T05:04:43Z

vuepress/docs/next/docs/curate/bundle-component-details.md

+      </html>
+
+## Pages
+This descriptor creates a page in a bundle. Page status can be `published` or `draft`. A widget can be applied to fully configure a page layout. 


are published and draft lowercase? i'm almost 100% we have these capitalized elsewhere; i think i worked on the page where they are, so if they should be lowercase i'll fix that at some point

Now that you mention it, I don't know where pages are in draft mode. I know content can be displayed that way but pages just have that yellow/green dot for status. will ask Nathan

This is a code thing and not shown in app builder, or if it is, it translates to published or unpublished. It is a status for the descriptor yaml. I was looking for it in the app builder but it's something set in the yaml and ECR publishes it according to this.

Leave the status lowercase and set to published and draft. That's part of the spec, as I understand it.

Lyd1aCla1r3 · 2022-09-20T05:14:26Z

vuepress/docs/next/docs/curate/bundle-versions-faq.md

-```
+### 1. Does the Entando Platform support bundle versioning?
+A bundle is an independent package containing one or more components. 
+As in other packaging systems, the [Entando Component Registry](../compose/ecr-overview.md)()(ECR) supports bundle versioning, allowing developers to create and release improvements of their package over time.


improvements -> iterations (no judging)

that's true but iterations is a hard word and improvements can be understood in the same way

Lyd1aCla1r3 · 2022-09-20T05:15:35Z

vuepress/docs/next/docs/curate/bundle-versions-faq.md


-Entando requires versions to follow the [semantic versioning 2.0.0](https://semver.org/#semantic-versioning-200), with the possibility to prepend a `v` to the version itself. Some valid bundle versions are:
+### 2. My bundle contains a microservice generated with the Entando Component Generator, does the version of the microservice have to be the same as the bundle version?


should be two sentences or a semicolon instead of a comma

Lyd1aCla1r3 · 2022-09-20T13:58:36Z

vuepress/docs/next/docs/curate/bundle-versions-faq.md

-    git tag -a "2.0.0" -m "My new version"
-    git push --tags
-```
+Bundle versions are defined by the creator and set in the bundle descriptor entando.json. You can have multiple versions of a bundle as long as they are defined and tagged as such.


i think entando.json is one of the files we've been backticking regularly

"defined and tagged as such" is a little muddled; circular referencing ends up as "defined and tagged as multiple versions" -> "uniquely defined and tagged"

Lyd1aCla1r3 · 2022-09-20T14:00:03Z

vuepress/docs/next/docs/curate/bundle-versions-faq.md

+```json
+{
+  "name": "my-bundle",
+  "description": "This is a description of my-bundle",


are we making an exception here for our usual placeholder format? not sure all caps is the way to go

this is because it is in the code. We may want to revisit this issue because it is getting confusing, especially when discussing code, we're supposed to cap to YOUR-THING but if it references code, we can't. In most of the code engineering puts out, the samples mostly use 'my' so we need to reference the same, Nathan pointed out

Lyd1aCla1r3 · 2022-09-20T14:36:41Z

vuepress/docs/next/docs/curate/bundle-versions-faq.md


+This gives the bundle developer complete control over the bundle release process, especially in those situations where the bundle contains more components and even more microservices.


i think "complete control over the bundle release process" is broader than this and entails more than versioning; reword slightly to scale back / refine? like complete control over the scope of the release, but not the process; the user is never modifying the process created by entando wrt bundle release

"...contains more components and even more MS" ?? this is a bit confusing and i think misleading - the number of microservices doesn't have to be greater than the number of components for targeted releases to come in handy. i think your point is that the more components the more opportunity for MS so the greater the benefit of being able to release on the MS level instead of the bundle level. that kind of granularity accommodates and tracks minor or specific changes without touching the bundle as a whole

this was what was there before. removed 'complete'.

the sentence is qualified by in those situations, but simplified

it's more like why introduce components when versioning applies to MS and bundles? without bridging the gap that components are likely to require MS, thus increasing the number of MS, it's kind of incongruous to bring components into the equation. versioning doesn't apply to components in general, right? -> "...the bundle contains many microservices" would kill my comment

You can version ms and mfe. I think you can also version platform components but that's not going to show up in the bundle on Entando?? Used components because that encompasses any/all parts. It doesn't necessarily refer to platform components in general use.

nshaw · 2022-09-21T19:02:46Z

vuepress/docs/next/docs/curate/bundle-component-details.md

+    groups/
+    labels/
+    pageTemplates/
+      template.yaml


Minor, since section is for the structure, we could probably remove the .yaml examples, or alternatively make them more specific, e.g. my-page-template.yaml, my-page.yaml, etc.

nshaw · 2022-09-21T19:04:41Z

vuepress/docs/next/docs/curate/bundle-component-details.md

+    contentType: CNG
+    description: Demo Content Template
+
+    # Optional. Define the content template shape in a separate file or inside the descriptor file with `contentShape`


Imho, shape is a terrible name for this but it's a legacy term. I read this as shape = structure.

nshaw · 2022-09-21T19:06:43Z

vuepress/docs/next/docs/curate/bundle-versions-faq.md

-Each version in the `tags` object must correspond a tag in the Git repository provided in the `tarball` field.
+## How-Tos
+### 1. How do I create a new version of a bundle?
+To release new versions of your bundle after changes have been made, edit the `entando.json` with the new version number for the bundle, then pack and publish your images to Docker. Docker will provide tags to update the bundle version. Once you deploy and install the bundle, the new version number will appear in the App Builder and automatically update in your apps. 


Minor, remove "and automatically update in your apps". It's not the version number that automatically updates. And, technically, the bundle update isn't automatic either since someone/something has to perform the install in the UI or via CLI.

nshaw · 2022-09-21T19:07:42Z

vuepress/docs/next/docs/curate/bundle-versions-faq.md


-If, for some reason, you don't want a particular version to be available for the installation, you can proceed as follows:
+- 1.0


My bad on the earlier pass, we require x.y.z (or vx.y.z) so this line should be 1.0.0

ENDOC-565 first pass

81ae3e2

jyunmitch requested review from nshaw and Lyd1aCla1r3 September 19, 2022 21:02

nshaw suggested changes Sep 20, 2022

View reviewed changes

Lyd1aCla1r3 reviewed Sep 20, 2022

View reviewed changes

jyunmitch added 2 commits September 20, 2022 14:13

ENDOC-565 review edits

725ed7c

ENDOC-565 minor edits

d1cb2a7

nshaw suggested changes Sep 21, 2022

View reviewed changes

ENDOC-565 final edits

8dbfb4a

nshaw approved these changes Sep 22, 2022

View reviewed changes

nshaw merged commit d3bed12 into main Sep 22, 2022

nshaw deleted the ENDOC-565 branch September 22, 2022 16:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENDOC-565 first pass #574

ENDOC-565 first pass #574

jyunmitch commented Sep 19, 2022

nshaw Sep 20, 2022

nshaw Sep 20, 2022

nshaw Sep 20, 2022

Lyd1aCla1r3 Sep 20, 2022

jyunmitch Sep 20, 2022

Lyd1aCla1r3 Sep 21, 2022

jyunmitch Sep 21, 2022 •

edited

Loading

Lyd1aCla1r3 Sep 20, 2022

jyunmitch Sep 20, 2022

jyunmitch Sep 20, 2022

nshaw Sep 20, 2022

Lyd1aCla1r3 Sep 20, 2022

jyunmitch Sep 20, 2022

Lyd1aCla1r3 Sep 20, 2022

Lyd1aCla1r3 Sep 20, 2022

Lyd1aCla1r3 Sep 20, 2022

jyunmitch Sep 20, 2022

Lyd1aCla1r3 Sep 20, 2022

jyunmitch Sep 20, 2022

Lyd1aCla1r3 Sep 21, 2022

jyunmitch Sep 21, 2022

nshaw Sep 21, 2022

nshaw Sep 21, 2022

nshaw Sep 21, 2022

nshaw Sep 21, 2022

		# Bundle Component Descriptors


		Elements such as simple widgets, page templates, groups, and static resources are classified as platform components on Entando. This page describes each of these elements with an example.


		Entando requires versions to follow the [semantic versioning 2.0.0](https://semver.org/#semantic-versioning-200), with the possibility to prepend a `v` to the version itself. Some valid bundle versions are:
		### 2. My bundle contains a microservice generated with the Entando Component Generator, does the version of the microservice have to be the same as the bundle version?


		This gives the bundle developer complete control over the bundle release process, especially in those situations where the bundle contains more components and even more microservices.


		If, for some reason, you don't want a particular version to be available for the installation, you can proceed as follows:
		- 1.0

ENDOC-565 first pass #574

ENDOC-565 first pass #574

Conversation

jyunmitch commented Sep 19, 2022

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 Sep 21, 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

jyunmitch Sep 21, 2022 •

edited

Loading