Merge branch 'main' into draft-messages

Author: johannes-vogel

.github/workflows/PR-SAP.yml

@@ -9,6 +9,9 @@ concurrency:
   group: pr-sap-${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   build-sap:
     runs-on: ubuntu-latest

.github/workflows/PR.yml

@@ -8,6 +8,9 @@ concurrency:
   group: pr-${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest

about/features.md

@@ -47,10 +47,13 @@ Following is an index of the features currently covered by CAP, with status and
 | [Compile cds models to different outputs](../node.js/cds-compile)          | `cds compile <models>`     |
 | [Run your services in local server](../node.js/cds-serve)                  | `cds serve <services>`     |
 | [Run and restart on file changes](../get-started/in-a-nutshell)            | `cds watch`                |
-| [Read-eval-event loop](../node.js/cds-env#cli)  <!-- TODO -->              | `cds repl`                 |
+| [Read-eval-event loop](../node.js/cds-env#cli)                             | `cds repl`                 |
 | Inspect effective configuration                                            | `cds env`                  |
 | Prepare for deployment                                                     | `cds build`                |
-| Deploy to databases or cloud                                               | `cds deploy`               |
+| Deploy to databases                                                        | `cds deploy`               |
+| Build and deploy your application to the cloud                             | `cds up`                   |
+| Bind application to remote services                                        | `cds bind`                 |
+| Debug your application                                                     | `cds debug`                |
 | Login to multitenant SaaS application                                      | `cds login <app-url>`      |
 | Upgrade SaaS tenant(s) to latest versions                                  | `cds upgrade`              |
 | Logout from multitenant SaaS application                                   | `cds logout`               |

guides/deployment/assets/github-deployment.png

@@ -16,6 +16,116 @@ status: released
 [[toc]]
 
 
+
+
+## GitHub Actions
+
+GitHub offers continuous integration using [GitHub Actions](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration). In our [samples](https://github.com/capire/samples), we use simple workflows to [test, deploy and release new versions](https://github.com/capire/samples/tree/main/.github/workflows).
+
+Add a default set of workflows to your project like so:
+
+```sh
+cds add github-actions
+```
+> You can also use `cds add gha` as a shortcut.
+
+### Deploy to Staging
+
+The created workflows do a _Staging_ deployment for pushes on the `main` branch, for example after merging pull requests.
+
+If no defaults are maintained in your GitHub org, a set of variables and secrets has to be provided. Open the repository and navigate here to maintain them:
+
+`Settings` → `Secrets and variables` → `Actions`
+
+For a minimal deployment setup, these variables and secrets are required:
+
+#### Cloud Foundry
+
+| **Type**   | **Name**       | **Note**  | **Example**       |
+|------------|----------------|-----------|-------------------|
+| Variable   | `CF_API`       | API URL   | `https://api.cf.example.com` |
+|    | `CF_USERNAME`  | Username  | `user@example.com` |
+|    | `CF_ORG`       | Org Name  | `my-org`          |
+|    | `CF_SPACE`     | Space Name| `my-space`        |
+| Secret     | `CF_PASSWORD`  | Password  | `********`        |
+
+#### Kyma
+
+| **Type**   | **Name**       | **Note**  | **Example**       |
+|------------|----------------|-----------|-------------------|
+| Secret   | `KUBE_CONFIG`       | Base64-encoded Kubernetes config   | see below |
+
+
+::: details Example of a decoded `KUBE_CONFIG`
+
+Your `KUBE_CONFIG` will have to look similar to this. Make sure to replace `token` by an authorization token created for your technical user used for deployment.
+
+```yaml{6-7,11}
+apiVersion: v1
+kind: Config
+clusters:
+  - name: default-cluster
+    cluster:
+      certificate-authority-data: ...
+      server: https://api.<server ID>.stage.kyma.ondemand.com
+users:
+  - name: ci-user
+    user:
+      token: ...
+contexts:
+  - name: ci-context
+    context:
+      cluster: default-cluster
+      namespace: ci
+      user: ci-user
+current-context: ci-context
+```
+[Learn more about configuring Kubernetes](./to-kyma#configure-kubernetes){.learn-more style="margin-top:20px"}
+
+:::
+
+#### BTP Prerequisites
+
+Also make sure sufficient service entitlements are assigned to your subaccount depending on your expected usage.
+
+::: tip Set up a sandbox subaccount as an org-wide default
+
+Organization variables and secrets allow you to provide defaults for new projects without prior setup.
+
+Once required for your use case, you can easily **overwrite org-wide** variables and secrets by **repository-local** ones.
+:::
+
+#### You're set!
+
+You can now simply push any CAP project that was set up using `cds add github-actions` to your org. When merging PRs or pushing to your `main` branch, the deployment workflow will start and after some time a new entry will show up in the _Deployments_ section on your repository front page:
+
+![](./assets/github-deployment.png){style="max-width: 200px"} <!-- = image-width/2 -->
+
+### Create a GitHub Release
+
+#### Prerequisites
+
+For the actual release we want to override org-wide sandbox variables to deploy to a different subaccount/organization and database.
+
+Go to `Settings` → `Environments` → `New environment` → enter "Production".
+
+Now override org-wide variables (e.g. `CF_ORG` and `CF_SPACE` in Cloud Foundry) to use a dedicated subaccount you created for the release deployment.
+
+#### Publish the release
+
+On your repository front page go to `Releases` → `Draft a new release` → `Select tag`.
+
+Now enter a tag name, e.g. `v1.0.0` and select `Create new tag: v1.0.0 on publish`.
+
+You can optionally add a release title and release notes. Hit **Publish release** once you're ready.
+
+The release will show up in your _Releases_ page and a deployment to your production environment is started. Once finished, a _Production_ entry shows up next to _Staging_:
+
+![](./assets/github-release.png){style="max-width: 268px"} <!-- = image-width/2 -->
+
+
+
+
 <span id="afterstart" />
 
 <span id="beforecicd" />
@@ -35,8 +145,3 @@ For more flexibility you can set up continuous delivery in your software develop
 Try the tutorial [Create Automated System Tests for SAP Cloud Application Programming Model Projects](https://developers.sap.com/tutorials/cicd-wdi5-cap.html) to create system tests against a CAP-based sample application and automate your tests through a CI/CD pipeline.
 
 [See a comparison with SAP Continuous Integration and Delivery Service.](https://www.project-piper.io/){.learn-more}
-
-## GitHub Actions
-
-GitHub offers continuous integration workflows using [GitHub Actions](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration). In our [SFlight sample,](https://github.com/SAP-samples/cap-sflight) we use GitHub Actions in two simple workflows to test our samples on [current Node.js and Java versions](https://github.com/SAP-samples/cap-sflight/tree/main/.github/workflows).
-

guides/deployment/assets/github-release.png

@@ -394,10 +394,6 @@ Searches the `title` element only.
 
 ##### Extend Search to *Associated* Entities
 
-::: warning Node.js: Only w/ streamlined database services
-For Node.js projects, this feature is only available with the [streamlined `@cap-js/` database services](../releases/archive/2024/jun24#new-database-services-ga) (default with `@sap/cds` >= 8)
-:::
-
 ```cds
 @cds.search: { author }
 entity Books { ... }

guides/deployment/cicd.md

@@ -4,7 +4,7 @@
 
 | your-project           | <Add your repository here>              |
 | ---------------------- | --------------------------------------- |
-| @sap/cds               | 9.2.0                                   |
+| @sap/cds               | 9.2.1                                   |
 | @sap/cds-dk            | -- missing --                           |
 | @sap/cds-compiler      | 6.2.2                                   |
 | @sap/cds-dk (global)   | 9.2.0                                   |

guides/providing-services.md

@@ -2,7 +2,7 @@
 <pre class="log">
 > cds version
 
-<em>@sap/cds</em>: 9.2.0
+<em>@sap/cds</em>: 9.2.1
 <em>@sap/cds-dk</em>: undefined
 <em>@sap/cds-compiler</em>: 6.2.2
 <em>@sap/cds-dk (global)</em>: 9.2.0

tools/assets/help/cds-version-md.out.md

@@ -33,21 +33,12 @@ export default [
 
 const defaultPackageJson = JSON.parse(data['package.json']);
 
-function mergeJSONs(target: any, add: any) {
-    const isObject = (obj: unknown) => typeof obj === 'object';
-    Object.entries(add).forEach(([key, addVal]) => {
-        const targetVal = target[key];
-        if (targetVal && isObject(targetVal) && isObject(addVal)) {
-            if ((Array.isArray(targetVal) && Array.isArray(addVal))) {
-                targetVal.push(...addVal);
-                return;
-            }
-            mergeJSONs(targetVal, addVal);
-        } else {
-            target[key] = addVal;
-        }
-    });
-    return target;
+const is_object = x => typeof x === 'object' && x !== null && !Array.isArray(x)
+function merge (o:any,...xs:any) {
+  let v:any; for (let x of xs) for (let k in x)
+    if (k === '__proto__' || k === 'constructor') continue //> avoid prototype pollution
+    else o[k] = is_object(v=x[k]) ? merge(o[k]??={},v) : v
+  return o
 }
 
 function link(name: Props['name'] = "", kind: Props['kind'], rules?: Props['rules'], files?: Props['files'], packages?: Props['packages'] ): string {
@@ -66,7 +57,7 @@ function link(name: Props['name'] = "", kind: Props['kind'], rules?: Props['rule
     sources[configFileName] = defaultConfig;
   }
   if (packages) {
-    json = mergeJSONs(defaultPackageJson, packages);
+    json = merge(defaultPackageJson, packages);
   } else {
     json = defaultPackageJson;
   }