Skip to content

Commit 47f0e94

Browse files
renejeglinskypatricebenderagoerlerswaldmannvincentatsap
authored
November Release (#2250)
Co-authored-by: Patrice Bender <[email protected]> Co-authored-by: Adrian Görler <[email protected]> Co-authored-by: Steffen Waldmann <[email protected]> Co-authored-by: vincentatsap <[email protected]> Co-authored-by: Robin <[email protected]> Co-authored-by: Johannes Vogel <[email protected]> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: chgeo <[email protected]> Co-authored-by: Evgeny Andreev <[email protected]> Co-authored-by: Simon Kobler <[email protected]> Co-authored-by: Olena <[email protected]> Co-authored-by: DJ Adams <[email protected]> Co-authored-by: Christian Georgi <[email protected]> Co-authored-by: Matthias Schur <[email protected]> Co-authored-by: Marc Becker <[email protected]> Co-authored-by: Mahati Shankar <[email protected]> Co-authored-by: simonoswald <[email protected]> Co-authored-by: Johannes Vogt <[email protected]> Co-authored-by: Vladislav Leonkev <[email protected]> Co-authored-by: Antonio Maradiaga <[email protected]> Co-authored-by: sjvans <[email protected]> Co-authored-by: SkylarkA <[email protected]> Co-authored-by: Modood Alvi <[email protected]> Co-authored-by: Steffen Weinstock <[email protected]>
1 parent dea3a59 commit 47f0e94

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+1569
-1259
lines changed

‎.github/workflows/ai-review.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: AI Review
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
merge_group:
7+
8+
concurrency:
9+
group: pr-sap-${{ github.workflow }}-${{ github.head_ref || github.run_id }}
10+
cancel-in-progress: true
11+
12+
jobs:
13+
ai-review:
14+
name: AI Review
15+
if: ${{ contains(github.event.pull_request.labels.*.name, 'AI Review') }}
16+
runs-on: ubuntu-latest
17+
permissions:
18+
contents: read
19+
pull-requests: write
20+
steps:
21+
- uses: SAP/ai-assisted-github-actions/pr-review@v3
22+
with:
23+
aicore-service-key: ${{ secrets.AICORE_SERVICE_KEY }}
24+
model: anthropic--claude-4-sonnet
25+
model-parameters: '{"temperature": 0.1}'
26+
prompt: |
27+
- As an AI bot reviewing documentation pull requests on GitHub, please focus on the following areas to ensure high-quality and effective documentation:
28+
- Use U.S. English spelling and punctuation.
29+
- Check for spelling errors and provide corrections.
30+
- Identify and correct grammatical errors and incorrect punctuation.
31+
- 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.
32+
- Consider the guidelines that can be found in .github/workflows/assets/editor.md and apply them.
33+
- Ensure that the tone is appropriate for technical documentation, maintaining a professional and informative style.
34+
- Verify that the structure of the document is logical and that headings and subheadings are used effectively.
35+
- Check for consistency in terminology and style throughout the document.
36+
- Use active voice instead of passive voice
37+
- Use present tense and **avoid future tense**!

‎.github/workflows/assets/editor.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
description: Reviews code for quality and best practices
3+
mode: subagent
4+
temperature: 0.1
5+
prompt: Do a detailed edit as outlined in the following.
6+
---
7+
8+
# Detailed Edit
9+
## ROLE
10+
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.
11+
12+
## TASK
13+
Perform a structured review of the text, checking compliance with the following categories:
14+
15+
1. Grammar & Style
16+
17+
- Use U.S. English spelling and punctuation.
18+
- Prefer active voice and present tense.
19+
- Allow passive voice only when explaining a system process.
20+
- Use common contractions, but avoid them in warnings or important messages.
21+
- Use colons, parentheses, question marks, and intensifiers judiciously.
22+
- Avoid exclamation marks, and abbreviations.
23+
- 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.
24+
- Spell out numbers one through nine in full. Use numerals for 10 and higher.
25+
- 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."
26+
- Ensure lists are parallel.
27+
- Avoid wordy constructions.
28+
29+
2. Clarity & Readability
30+
31+
- Write clear, concise, and short sentences that are easy to understand.
32+
- Avoid jargon, colloquialisms, dialect, clipped words, and unnecessary complexity.
33+
- Avoid hyperbole.
34+
- Use positive formulations.
35+
- 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.
36+
- Do not remove markdown-specific formatting like _document URLs_.
37+
- Do not edit code samples, not even whitespace.
38+
- Do not touch <Config> tags, as these have a special meaning and need to be preserved.
39+
40+
3. Consistency & Tone
41+
42+
- Use the personal pronoun “you” and make sure the user is the center of the narrative.
43+
- 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.
44+
45+
4. Inclusivity & Ethical Considerations
46+
47+
- Avoid stereotypes, discrimination, and biases.
48+
- Check for stopwords, including: abort, execute, grandfather, terminate, kill, disable, whitelist, blacklist, slave, master)
49+
- 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."
50+
- 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.
51+
- Output the detected topics as a Python list. If no topics are found, output: "Language checked."
52+
- 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:
53+
Instead of "See the highlighted section," → Use "Note the highlighted sections."
54+
Instead of "Did you hear the announcement?" → Use "Did you receive the announcement?"
55+
Note: "See" is ok when used to mean "refer to" → "For more information, see Troubleshooting."
56+
57+
5. Formality & Suitability
58+
59+
- Avoid emoticons and emojis.
60+
- Do NOT remove TODO markers at all.
61+
- Do NOT remove tip, warning or danger notes indicated by `::: tip` or similar constructs.
62+
63+
6. Guidelines
64+
For this repository you should consider the following guideline:
65+
66+
To have a consistent look and feel throughout capire, use the following semantic when formatting your text.
67+
68+
| Format | Semantic |
69+
|---|---|
70+
| _Italic_ | Indicates new terms, URLs, email addresses, filenames, and file extensions, and UI Elements.|
71+
|`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.|
72+
73+
It boils down to very basic considerations:
74+
75+
- Everything that is code or related to code, which includes configuration, is at `Constant width`
76+
- Everything else, that is neither code nor configuration, is _Italic_
77+
- Everything that is important and should be highlighted is **Bold**
78+
- Keywords and all other things you want to highlight, can be formatted as `Constant width` but it should be used wisely.
79+
80+
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.
81+
82+
- Use active voice instead of passive voice
83+
84+
Example: Add the parameter `xyz` to ... ✅ | The parameter `xyz` is added to ... ❌
85+
- Be friendly and conversational, put yourself in the users shoes.
86+
87+
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.
88+
- Use simple language.
89+
90+
This sound easier than it is, but if you can put it in simpler words, it gets automatically clearer and more helpful.
91+
92+
Use present and avoid future tense!
93+
94+
The documentation should follow the here described style guidance so that it keeps a consistent external and internal appearance:
95+
96+
| Topic | Write | Don't Write |
97+
|----------------------------------|----------------------------------|--------------------------------------------------------------------------------|
98+
| Single quotes | isn't, or don't | isn’t, or don’t |
99+
| The other single quote: ‘ | ' | ‘ |
100+
| In-text, in-line, single quoting | \`assets\` (showing as `assets`) | \`\`assets\`\`, or \`\`\`assets\`\`\` (showing as ``assets``, or ```assets```) |
101+
| JavaScript code snippets | \`\`\`js | \`\`\`javascript |
102+
| Three dots | ... (good: 3 1-dot characters) | … (bad: 1 3-dot characters) |
103+
| Long dash | --- (good: 3 single dashes) | —, &mdash;, &ndash; (bad: long-dash character, \&mdash; or \&ndash;) |
104+
105+
| Terminology | Don't Write |
106+
|-------------------------------------------------------------------------|-------------------------------|
107+
| for example | e.g. <sup>1</sup> |
108+
| GitHub | Github, github <sup>2</sup> |
109+
| that is | i.e. <sup>1</sup> |
110+
| Java | JAVA, java <sup>2</sup> |
111+
| micro service | micro-service, microservice |
112+
| modeling | modelling |
113+
| multitarget | multi-target, multi target |
114+
| multitenancy | multi-tenancy, multi tenancy |
115+
| multitenant | multi-tenant, multi tenant |
116+
| Node.js | node.js <sup>2</sup> |
117+
| SAP BTP | SAP CP, CP |
118+
| SAP HANA | HANA, Hana, hana <sup>2</sup> |
119+
| SAP Software-as-a-Service Provisioning service | saas registry <sup>2</sup> |
120+
| SQLite | SqLite, sqlite <sup>2</sup> |
121+
| versus | vs. <sup>1</sup> |
122+
| XSUAA | xsuaa <sup>2</sup> |
123+
124+
<sup>1</sup> Avoid latin abbreviations.<br>
125+
<sup>2</sup> Use the not recommended spelling only if you're clearly referring to some technical entity or process.
126+
127+
> 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.
128+
129+
To improve readability and translatability, avoid using modal verbs in your content.
130+
131+
## FINAL STEPS
132+
Provide a report summarizing how well the text adheres to the writing rules, highlighting issues found in each category.
133+
Rewrite the text to align with all guidelines while maintaining clarity, accuracy, and user focus.
134+
Explain each change by displaying every sentence of the revised text along with a justification for what was modified or retained.
135+
Finally, output the revised text in its entirety.

‎.vitepress/config.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,8 +106,8 @@ config.rewrites = rewrites
106106
// Add custom capire info to the theme config
107107
config.themeConfig.capire = {
108108
versions: {
109-
java_services: '4.4.1',
110-
java_cds4j: '4.4.1'
109+
java_services: '4.5.0',
110+
java_cds4j: '4.5.0'
111111
},
112112
gotoLinks: []
113113
}

‎.vitepress/theme/components/ConfigInspect.vue‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,13 @@
3636
import FloatingVue from 'floating-vue'
3737
import yaml from 'yaml'
3838
39-
const { java, keyOnly, filesOnly, showPrivate, label:labelProp } = defineProps<{
39+
const { java, keyOnly, filesOnly, showPrivate, label:labelProp, keyDelim } = defineProps<{
4040
java?: boolean,
4141
keyOnly?: boolean,
4242
filesOnly?: boolean,
4343
showPrivate?: boolean,
44-
label?: string
44+
label?: string,
45+
keyDelim?: string
4546
}>()
4647
4748
// sub component that renders code blocks similar to the markdown `::: code-block` syntax
@@ -85,6 +86,7 @@
8586
8687
const [key, val] = slotVal.split(/\s*[:=]\s*(.*)/) // split on first `:` or `=`
8788
const label = labelProp || `${keyOnly ? key: slotVal}`
89+
const keyDel = keyDelim ?? '.'
8890
8991
const cfgKey = ref()
9092
const popperVisible = ref(false)
@@ -114,25 +116,25 @@
114116
115117
let jsonVal
116118
if (typeof value === 'string' && value.trim().match(/^[[{].*[\]}]$/)) { try { jsonVal = JSON.parse(value) } catch {/*ignore*/ } }
117-
const pkg = toJson(key, jsonVal ?? value)
119+
const pkg = toJson(key, jsonVal ?? value, keyDel)
118120
119121
pkgStr.value = JSON.stringify(pkg, null, 2)
120122
rcJsonStr.value = JSON.stringify(pkg.cds??{}, null, 2)
121123
rcJsStr.value = 'module.exports = ' + rcJsonStr.value.replace(/"(\w*?)":/g, '$1:')
122124
rcYmlStr.value = yaml.stringify(pkg.cds)
123-
propStr.value = `${key}=${jsonVal ? JSON.stringify(jsonVal) : value}`
124125
125-
let envKey = key.replaceAll('_', '__').replaceAll('.', '_')
126+
let envKey = key.replaceAll('_', '__').replaceAll(keyDel, '_')
126127
if (/^[a-z_]+$/.test(envKey)) envKey = envKey.toUpperCase() // only uppercase if not camelCase
127128
envStr.value = `${envKey}=${jsonVal ? JSON.stringify(jsonVal) : value}`
129+
propStr.value = `${envKey}=${jsonVal ? JSON.stringify(jsonVal) : value}`
128130
129131
javaAppyml.value = yaml.stringify(pkg)
130132
javaEnvStr.value = `-D${propStr.value}`
131133
})
132134
133-
function toJson(key:string, value:string): Record<string, any> {
135+
function toJson(key:string, value:string, delim:string): Record<string, any> {
134136
let res = {}
135-
const parts = key.split('.')
137+
const parts = key.split(delim)
136138
parts.reduce((r:Record<string,any>, a, i) => {
137139
r[a] = r[a] || (i < parts.length-1 ? {} : value)
138140
return r[a];

‎.vitepress/theme/styles.scss‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -115,11 +115,11 @@ main {
115115
// Custom list styles for nested items
116116
ul {
117117
list-style-type: disc; // First level: filled circle
118-
118+
119119
ul {
120120
list-style-type: circle; // Second level: empty circle
121-
122-
121+
122+
123123
ul {
124124
list-style-type: square; // Third level: square
125125
}
@@ -299,6 +299,11 @@ main {
299299
border-width: 0 0 0 7px;
300300
border-radius: 14px;
301301

302+
.learn-more {
303+
margin-top: 10px;
304+
margin-bottom: -5px;
305+
}
306+
302307
&.note {
303308
background-color: #f6f6f6;
304309
border-color: #bbb;
@@ -551,15 +556,14 @@ html.node {
551556
pre.log:focus {
552557
min-width: fit-content;
553558
padding-right: 40px;
554-
z-index: 1; // draw over outline
559+
z-index: 1; position: relative; // draw over outline
555560
}
556561
table:hover,
557562
table:focus {
558563
min-width: fit-content;
559564
}
560-
tr { // make wide rows go over outline, not below it
561-
z-index: 1;
562-
position: relative;
565+
tr {
566+
z-index: 1; position: relative; // draw wide rows over outline
563567
}
564568
[class*='language-'] pre {
565569
overflow: hidden !important;

0 commit comments

Comments
 (0)