search

SAP-docs / btp-cloud-platform

Markdown source for the SAP BTP documentation. Enables feedback and contributions to improve the documentation.
Creative Commons Attribution 4.0 International
50 stars 95 forks source link

Feedback for "Content Deployment" #123

Closed piejanssens closed 1 year ago

piejanssens commented 1 year ago

https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/d3e23196166b443db17b3545c912dfc0.html

The workflow module sample is not showing how the actual workflow content is included in the content-module.

DavidMitreski5 commented 1 year ago

Thank you for your feedback! We’ll look into it and come back to you if we have any questions.

lilyanarangelova commented 1 year ago

Thank you for your feedback. I'll forward it to my developers.

boyan-velinov commented 1 year ago

@piejanssens Hello, I would assume you are aiming the first example under section "Delivering file content". In this section there are snippets of both MTA descriptor (mtad.yaml) and MANIFEST.MF. The combination of both is used to define file location in the MTA archive and how to proceed. Since MTA archive complies with JAR specification, the path to binaries is defined in MANIFEST.MF. In that example MANIFEST.MF describe where is the actual workflow content -> in subdirectory content-module/data

In other page it is described what is the syntax and content of MANIFEST.MF in context of MTA archives: https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/33a0e0eb1e4a47b3af52596b87fd2cef.html

Other examples below are just snippets of MTA descriptors (mtad.yaml). They do not provide MANIFEST.MF because it will be the same sample at all.

piejanssens commented 1 year ago

Hi @boyan-velinov,

I'm not saying that the provided examples are wrong. The point is that these are too low level. We are used to work with a higher level "project MTA development descriptor" mta.yaml and let SAP's Cloud MTA Build tool deal with generating the mtad.yaml, MANIFEST.MF and package it in an archive.mtar.

Since it has no added value for us as developers, we shouldn't see this level in the SAP Help section on Content Deployment, instead we should see an example of an mta.yaml. It's easier to only deal with one descriptor file instead of both a descriptor and the manifest.

Defining Multitarget Application Development Descriptors in the BTP documentation for Cloud Foundry: The MTA development descriptor (mta.yaml) is used to generate the deployment descriptor (mtad.yaml), which is required for deploying an MTA to the target runtime.

The next sentence on that same page is confusing or incorrect: If you use command-line tools to deploy an MTA, you do not need an mta.yaml file. However, in these cases you have to manually create the mtad.yaml file. Which command-line tools are being referred to? If it's cf's multiapps plugin, then you don't need to manually create the mtad.yaml file, you need SAP's Cloud MTA Build Tool...

In the MTA spec, the MANIFEST.MF is mainly discussed in the documentation of the mtar archive contents. Other sections (like the intro, MTA model, MTA descriptor) do not go into this detail and assume there is an IDE or script taking care of the mtar build process.

boyan-velinov commented 1 year ago

Hi @piejanssens

I agree that this page of the documentation is not helpful for developers who use SAP Business Application Studio and/or Cloud MTA Build Tool, namely starting with mta.yaml.

This part of the documentation is related to MTA deployment based on MTA deployment descriptor mtad.yaml, which might be inside of generated .mtar or outside. It serves as a reference documentation what is possible with mtad.yaml and yes it is on a lower level. Note that this documentation cannot cover all kind of apps, services and contents provided by BTP Cloud Foundry. Each entitiy might have some peculiarity and needs certain MTA modelling. A proper place for documnetation about certain kind of app, service or content is inside its own documentation or inside in the SAP Business Application Studio

About Workflow, I would assume this is the proper page: https://help.sap.com/docs/WORKFLOW/e157c391253b4ecd93647bf232d18a83/b2df7c220b2245dcad11be747794c042.html?version=Cloud&locale=en-US

The improvements that we can do in Content Deployment page are:

You are correct, the only one supported way to deploy MTA in CF from CMD is by using MultiApps CF CLI plugin.

MultiApps CLI plugin provides possibility to deploy already generated MTA arhive (.mtar), which is result from MBT. On the other side it provides possibility to deploy from directory that contains deployment descriptor (mtad.yaml) and already built app binaries.

Easy example can be seen into example repo: https://github.com/SAP-samples/cf-mta-examples/tree/main/cf-app#deploy-from-directory

The command cf deploy is also documented in SAP Help Portal: https://help.sap.com/docs/BTP/65de2977205c403bbc107264b8eccf4b/65ddb1b51a0642148c6b468a759a8a2e.html#deploy

Deploy from directory is useful when you maintain directly mtad.yaml (yes by hand) but you have the freedom to control the build of your apps - e.g. different builders, different sequence, etc.

Defining Multitarget Application Development Descriptors might be improved and we will work on that by aiming to be more clear and explicit.

Best Regards, Boyan

lilyanarangelova commented 1 year ago

I close this issue as Boyan already responded and the documentation is to be updated within next 2 weeks.