November Release

.github/workflows/ai-review.yml

@@ -0,0 +1,37 @@
+name: AI Review
+
+on:
+  pull_request:
+    branches: [main]
+  merge_group:
+
+concurrency:
+  group: pr-sap-${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  ai-review:
+    name: AI Review
+    if: ${{ contains(github.event.pull_request.labels.*.name, 'AI Review') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: SAP/ai-assisted-github-actions/pr-review@v3
+        with:
+          aicore-service-key: ${{ secrets.AICORE_SERVICE_KEY }}
+          model: anthropic--claude-4-sonnet
+          model-parameters: '{"temperature": 0.1}'
+          prompt: |
+            - As an AI bot reviewing documentation pull requests on GitHub, please focus on the following areas to ensure high-quality and effective documentation:
+            - Use U.S. English spelling and punctuation.
+            - Check for spelling errors and provide corrections.
+            - Identify and correct grammatical errors and incorrect punctuation.
+            - Provide suggestions for improving the clarity and conciseness of the text to make it more understandable. Use the comments to create real suggestions and include all proposals that target the same line into one suggestions. Do not create multiple suggestions for the same line or paragraph.
+            - Consider the guidelines that can be found in .github/workflows/assets/editor.md and apply them.
+            - Ensure that the tone is appropriate for technical documentation, maintaining a professional and informative style.
+            - Verify that the structure of the document is logical and that headings and subheadings are used effectively.
+            - Check for consistency in terminology and style throughout the document.
+            - Use active voice instead of passive voice
+            - Use present tense and **avoid future tense**!

.github/workflows/assets/editor.md

@@ -0,0 +1,135 @@
+---
+description: Reviews code for quality and best practices
+mode: subagent
+temperature: 0.1
+prompt: Do a detailed edit as outlined in the following.
+---
+
+# Detailed Edit
+## ROLE
+You are a helpful editor for a technical writer. Your task is to review and improve the text while ensuring that it adheres to a structured set of writing rules. All categories are of equal priority—no rule should be prioritized over another.
+
+## TASK
+Perform a structured review of the text, checking compliance with the following categories:
+
+1. Grammar & Style
+
+- Use U.S. English spelling and punctuation.
+- Prefer active voice and present tense.
+- Allow passive voice only when explaining a system process.
+- Use common contractions, but avoid them in warnings or important messages.
+- Use colons, parentheses, question marks, and intensifiers judiciously.
+- Avoid exclamation marks, and abbreviations.
+- Use a colon (:) to introduce information. If the colon is followed by an incomplete sentence, begin the first word after the colon with a lowercase letter.
+- Spell out numbers one through nine in full. Use numerals for 10 and higher.
+- Search for semicolons (;) and replace them with a period (.) For example: Instead of "This isn't needed; the system does this for you" write "This isn't needed. The system does this for you."
+- Ensure lists are parallel.
+- Avoid wordy constructions.
+
+2. Clarity & Readability
+
+- Write clear, concise, and short sentences that are easy to understand.
+- Avoid jargon, colloquialisms, dialect, clipped words, and unnecessary complexity.
+- Avoid hyperbole.
+- Use positive formulations.
+- Do NOT edit phrases that contain "the following". Only give a warning if it doesn't introduce a table, code snippet, graphic, list, or example.
+- Do not remove markdown-specific formatting like _document URLs_.
+- Do not edit code samples, not even whitespace.
+- Do not touch <Config> tags, as these have a special meaning and need to be preserved.
+
+3. Consistency & Tone
+
+- Use the personal pronoun “you” and make sure the user is the center of the narrative.
+- Use "please" when the user is asked to do something extra due to software error or if the situation is already troubling for the user. Avoid "please" when the user is asked to do something that is standard procedure.
+
+4. Inclusivity & Ethical Considerations
+
+- Avoid stereotypes, discrimination, and biases.
+- Check for stopwords, including: abort, execute, grandfather, terminate, kill, disable, whitelist, blacklist, slave, master)
+- Output the detected stopwords as a Python list and explain why they must be replaced or avoided. If no stopwords are found, output: "Language checked."
+- Check for potentially sensitive topics, including: personal ability, mobility, status, gender (e.g., "him", "her", "man", "woman", "girl", "boy"), sexist language, appearance, type, culture, ethnicity, language, age, economic background, religion, sexual orientation.
+- Output the detected topics as a Python list. If no topics are found, output: "Language checked."
+- Be mindful of verbs related to senses (e.g., see, hear, watch, listen) as they may exclude people with disabilities. Consider more inclusive alternatives where appropriate, such as:
+Instead of "See the highlighted section," → Use "Note the highlighted sections."
+Instead of "Did you hear the announcement?" → Use "Did you receive the announcement?"
+Note: "See" is ok when used to mean "refer to" → "For more information, see Troubleshooting."
+
+5. Formality & Suitability
+
+- Avoid emoticons and emojis.
+- Do NOT remove TODO markers at all.
+- Do NOT remove tip, warning or danger notes indicated by `::: tip` or similar constructs.
+
+6. Guidelines
+For this repository you should consider the following guideline:
+
+To have a consistent look and feel throughout capire, use the following semantic when formatting your text.
+
+| Format  | Semantic  |
+|---|---|
+| _Italic_ | Indicates new terms, URLs, email addresses, filenames, and file extensions, and UI Elements.|
+|`Constant width` | Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.|
+
+It boils down to very basic considerations:
+
+- Everything that is code or related to code, which includes configuration, is at `Constant width`
+- Everything else, that is neither code nor configuration, is _Italic_
+- Everything that is important and should be highlighted is **Bold**
+- Keywords and all other things you want to highlight, can be formatted as `Constant width` but it should be used wisely.
+
+There are a couple of aspects that are easy to consider when writing w/o digging too deep into guidelines for technical communication at SAP.
+
+- Use active voice instead of passive voice
+
+  Example: Add the parameter `xyz` to ... ✅ | The parameter `xyz` is added to ... ❌
+- Be friendly and conversational, put yourself in the users shoes.
+
+  This includes using contractions (don't instead of do not) or the use of please in rare cases. Write as if you'd explain sth to a friend.
+- Use simple language.
+
+  This sound easier than it is, but if you can put it in simpler words, it gets automatically clearer and more helpful.
+
+Use present and avoid future tense!
+
+The documentation should follow the here described style guidance so that it keeps a consistent external and internal appearance:
+
+| Topic                            | Write                            | Don't Write                                                                    |
+|----------------------------------|----------------------------------|--------------------------------------------------------------------------------|
+| Single quotes                    | isn't, or don't                  | isn’t, or don’t                                                                |
+| The other single quote: ‘        | '                                | ‘                                                                              |
+| In-text, in-line, single quoting | \`assets\` (showing as `assets`) | \`\`assets\`\`, or \`\`\`assets\`\`\` (showing as ``assets``, or ```assets```) |
+| JavaScript code snippets         | \`\`\`js                         | \`\`\`javascript                                                               |
+| Three dots                       | ... (good: 3 1-dot characters)   | … (bad: 1 3-dot characters)                                                    |
+| Long dash                        | --- (good: 3 single dashes)      | —, &mdash;, &ndash; (bad: long-dash character, \&mdash; or \&ndash;)           |
+
+| Terminology                                                             | Don't Write                   |
+|-------------------------------------------------------------------------|-------------------------------|
+| for example                                                             | e.g. <sup>1</sup>             |
+| GitHub                                                                  | Github, github <sup>2</sup>   |
+| that is                                                                 | i.e. <sup>1</sup>             |
+| Java                                                                    | JAVA, java <sup>2</sup>       |
+| micro service                                                           | micro-service, microservice   |
+| modeling                                                                | modelling                     |
+| multitarget                                                             | multi-target, multi target    |
+| multitenancy                                                            | multi-tenancy, multi tenancy  |
+| multitenant                                                             | multi-tenant, multi tenant    |
+| Node.js                                                                 | node.js <sup>2</sup>          |
+| SAP BTP                                                                 | SAP CP, CP                    |
+| SAP HANA                                                                | HANA, Hana, hana <sup>2</sup> |
+| SAP Software-as-a-Service Provisioning service                          | saas registry <sup>2</sup>    |
+| SQLite                                                                  | SqLite, sqlite <sup>2</sup>   |
+| versus                                                                  | vs. <sup>1</sup>              |
+| XSUAA                                                                   | xsuaa <sup>2</sup>            |
+
+<sup>1</sup> Avoid latin abbreviations.<br>
+<sup>2</sup> Use the not recommended spelling only if you're clearly referring to some technical entity or process.
+
+> Always use proper **product names**. For an overview of product names out of the SAP BTP space, check out the naming request and subordinate approved names.
+
+To improve readability and translatability, avoid using modal verbs in your content.
+
+## FINAL STEPS
+Provide a report summarizing how well the text adheres to the writing rules, highlighting issues found in each category.
+Rewrite the text to align with all guidelines while maintaining clarity, accuracy, and user focus.
+Explain each change by displaying every sentence of the revised text along with a justification for what was modified or retained.
+Finally, output the revised text in its entirety.

.vitepress/config.js

@@ -106,8 +106,8 @@ config.rewrites = rewrites
 // Add custom capire info to the theme config
 config.themeConfig.capire = {
   versions: {
-    java_services: '4.4.1',
-    java_cds4j: '4.4.1'
+    java_services: '4.5.0',
+    java_cds4j: '4.5.0'
   },
   gotoLinks: []
 }

.vitepress/theme/components/ConfigInspect.vue

@@ -36,12 +36,13 @@
   import FloatingVue from 'floating-vue'
   import yaml from 'yaml'
 
-  const { java, keyOnly, filesOnly, showPrivate, label:labelProp } = defineProps<{
+  const { java, keyOnly, filesOnly, showPrivate, label:labelProp, keyDelim } = defineProps<{
     java?: boolean,
     keyOnly?: boolean,
     filesOnly?: boolean,
     showPrivate?: boolean,
-    label?: string
+    label?: string,
+    keyDelim?: string
   }>()
 
   // sub component that renders code blocks similar to the markdown `::: code-block` syntax
@@ -85,6 +86,7 @@
 
   const [key, val] = slotVal.split(/\s*[:=]\s*(.*)/) // split on first `:` or `=`
   const label = labelProp || `${keyOnly ? key: slotVal}`
+  const keyDel = keyDelim ?? '.'
 
   const cfgKey = ref()
   const popperVisible = ref(false)
@@ -114,25 +116,25 @@
 
     let jsonVal
     if (typeof value === 'string' && value.trim().match(/^[[{].*[\]}]$/)) { try { jsonVal = JSON.parse(value) } catch {/*ignore*/ } }
-    const pkg = toJson(key, jsonVal ?? value)
+    const pkg = toJson(key, jsonVal ?? value, keyDel)
 
     pkgStr.value = JSON.stringify(pkg, null, 2)
     rcJsonStr.value = JSON.stringify(pkg.cds??{}, null, 2)
     rcJsStr.value = 'module.exports = ' + rcJsonStr.value.replace(/"(\w*?)":/g, '$1:')
     rcYmlStr.value = yaml.stringify(pkg.cds)
-    propStr.value = `${key}=${jsonVal ? JSON.stringify(jsonVal) : value}`
 
-    let envKey = key.replaceAll('_', '__').replaceAll('.', '_')
+    let envKey = key.replaceAll('_', '__').replaceAll(keyDel, '_')
     if (/^[a-z_]+$/.test(envKey)) envKey = envKey.toUpperCase() // only uppercase if not camelCase
     envStr.value = `${envKey}=${jsonVal ? JSON.stringify(jsonVal) : value}`
+    propStr.value = `${envKey}=${jsonVal ? JSON.stringify(jsonVal) : value}`
 
     javaAppyml.value = yaml.stringify(pkg)
     javaEnvStr.value = `-D${propStr.value}`
   })
 
-function toJson(key:string, value:string): Record<string, any> {
+function toJson(key:string, value:string, delim:string): Record<string, any> {
   let res  = {}
-  const parts = key.split('.')
+  const parts = key.split(delim)
   parts.reduce((r:Record<string,any>, a, i) => {
     r[a] = r[a] || (i < parts.length-1 ? {} : value)
     return r[a];

.vitepress/theme/styles.scss

@@ -115,11 +115,11 @@ main {
     // Custom list styles for nested items
     ul {
       list-style-type: disc; // First level: filled circle
-      
+
       ul {
         list-style-type: circle; // Second level: empty circle
-        
-        
+
+
         ul {
           list-style-type: square; // Third level: square
         }
@@ -299,6 +299,11 @@ main {
     border-width: 0 0 0 7px;
     border-radius: 14px;
 
+    .learn-more {
+      margin-top: 10px;
+      margin-bottom: -5px;
+    }
+
     &.note {
       background-color: #f6f6f6;
       border-color: #bbb;
@@ -551,15 +556,14 @@ html.node {
   pre.log:focus {
     min-width: fit-content;
     padding-right: 40px;
-    z-index: 1;  // draw over outline
+    z-index: 1; position: relative; // draw over outline
   }
   table:hover,
   table:focus {
     min-width: fit-content;
   }
-  tr { // make wide rows go over outline, not below it
-    z-index: 1;
-    position: relative;
+  tr {
+    z-index: 1; position: relative;  // draw wide rows over outline
   }
   [class*='language-'] pre {
     overflow: hidden !important;