feat: release version 1.8.0 with breaking changes, enhanced documentation, and new migration guide for value-help entities

Author: jung-thomas

CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
+## [1.8.0] - 2026-03-14
+
+**Changed**
+
+- Enhance README and improve project documentation
+- Add PostgreSQL profile-specific model exposure updates across CDS models and service projection
+- Add and expand Star Wars CDS model unit tests, including profile-specific exposure coverage
+- Update project dependencies and bump version to 1.8.0
+- Update dev container setup (Dockerfile and devcontainer.json) for Node.js LTS and Cloud Foundry CLI installation
+- Add CAP modeling and handler guidelines plus validation prompt workflows
+- Add compatibility-safe value-help entity migration (`*Values` helper entities) and keep legacy helper entities/projections with deprecation comments for phased removal
+- BREAKING: remove legacy value-help helper entities/projections (`climate`, `terrain`, `hair_colors`, `eye_colors`, `skin_colors`, `classification`, `designation`, `language`) in favor of `*Values` artifacts
+- Migration details: `cap/docs/value-help-migration.md`
+
 ## [1.4.0] - 2024-07-19
 
 **Changed**

README.md

@@ -63,6 +63,12 @@ From the Cloud Application Programming Model preview (which opens locally when u
 
 ![Fiori Preveiw Overview Edit](images/Fiori_Preview_Overview_Edit.png)
 
+## Upgrade Notes
+
+* **Breaking change**: legacy value-help helper endpoints were removed in favor of `*Values` entities.
+* Migration details and endpoint mapping are documented in:
+  * [`cap/docs/value-help-migration.md`](./cap/docs/value-help-migration.md)
+
 ## Known Issues
 
 If you receive an error like the following when running the convertData script
@@ -75,7 +81,7 @@ If you receive an error like the following when running the convertData script
 }
 ```
 
-This is caused by the parallel nature of the loading of the data in SQLite.  The default script with its parallel loading works fine when you use HANA as the target persistence. However if you are using SQLite for your tempoary testing persistence, then you can use the alternative convertDataLite script instead. 
+This is caused by the parallel nature of the loading of the data in SQLite.  The default script with its parallel loading works fine when you use HANA as the target persistence. However if you are using SQLite for your tempoary testing persistence, then you can use the alternative convertDataLite script instead.
 
 **Note**: due to some strange circumstances in the latest versions of CAP it seems the `/gen/srv` folder is getting cleared after any deployment to HANA.  Therefore just execute a `cds build` or `npm run build` after any deployment to restore the `/gen` folder until we find the root cause of this issue.
 

cap/CHANGELOG.json

@@ -1,4 +1,19 @@
 [
+    {
+        "date": "2026-03-14",
+        "version": "1.8.0",
+        "Changed": [
+            "Enhance README and improve project documentation",
+            "Add PostgreSQL profile-specific model exposure updates across CDS models and service projection",
+            "Add and expand Star Wars CDS model unit tests, including profile-specific exposure coverage",
+            "Update project dependencies and bump version to 1.8.0",
+            "Update dev container setup (Dockerfile and devcontainer.json) for Node.js LTS and Cloud Foundry CLI installation",
+            "Add CAP modeling and handler guidelines plus validation prompt workflows",
+            "Add compatibility-safe value-help entity migration (*Values helper entities) while retaining legacy helper entities/projections with deprecation comments",
+            "BREAKING: remove legacy value-help helper entities/projections (climate, terrain, hair_colors, eye_colors, skin_colors, classification, designation, language) in favor of *Values artifacts",
+            "Migration details: cap/docs/value-help-migration.md"
+        ]
+    },
     {
         "date": "2024-07-19",
         "version": "1.4.0",

cap/README.md

@@ -40,3 +40,9 @@ Learn more at <https://cap.cloud.sap/docs/get-started/>.
 - Run full model tests: `npm run test`
 - Run profile-scoping regression tests only: `npm run test:profile`
 - CI tip: use `npm run test:profile` as a fast gate for profile-specific model/service exposure checks.
+
+## Upgrade Notes
+
+- **Breaking change**: legacy value-help helper endpoints were removed in favor of `*Values` entities.
+- If your UI/integration code called legacy endpoints directly, update it using:
+  - `docs/value-help-migration.md`

cap/convertData.js

@@ -78,6 +78,30 @@ function normalizeDate(value) {
     return parsed.toISOString().slice(0, 10)
 }
 
+function normalizeBirthYear(value) {
+    const normalized = normalizeString(value)
+    if (!normalized) {
+        return null
+    }
+
+    const canonical = normalized.replaceAll(' ', '').toUpperCase()
+    if (!/^[0-9]+(?:BBY|ABY)$/.test(canonical)) {
+        return null
+    }
+
+    return canonical
+}
+
+function hasMandatoryValue(value, entityName, fieldName, sourcePk, report) {
+    if (value !== null && value !== undefined) {
+        return true
+    }
+
+    report.stats.skippedRecords += 1
+    report.warnings.push(`[MissingMandatory] ${entityName}.${fieldName}(${sourcePk}) is required`)
+    return false
+}
+
 function deterministicId(kind, sourceKey) {
     return uuidv5(`${kind}:${sourceKey}`, MIGRATION_ID_NAMESPACE)
 }
@@ -212,9 +236,14 @@ function transformFixtures(fixtures, report) {
     }
 
     for (const planet of planets) {
+        const name = normalizeString(planet.fields.name)
+        if (!hasMandatoryValue(name, 'Planet', 'name', planet.pk, report)) {
+            continue
+        }
+
         pushRow(rows.Planet, dedupe.Planet, {
             ID: planet.ID,
-            name: normalizeString(planet.fields.name),
+            name,
             diameter: normalizeString(planet.fields.diameter),
             rotation_period: normalizeString(planet.fields.rotation_period),
             orbital_period: normalizeString(planet.fields.orbital_period),
@@ -228,16 +257,21 @@ function transformFixtures(fixtures, report) {
 
     for (const person of people) {
         const homeworld = resolveReference(planetsByPk, person.fields.homeworld, `People.homeworld(${person.pk})`, report)
+        const name = normalizeString(person.fields.name)
+        if (!hasMandatoryValue(name, 'People', 'name', person.pk, report)) {
+            continue
+        }
+
         pushRow(rows.People, dedupe.People, {
             ID: person.ID,
             homeworld_ID: homeworld?.ID ?? null,
-            name: normalizeString(person.fields.name),
+            name,
             height: normalizeString(person.fields.height),
             mass: normalizeString(person.fields.mass),
             hair_color: normalizeString(person.fields.hair_color),
             skin_color: normalizeString(person.fields.skin_color),
             eye_color: normalizeString(person.fields.eye_color),
-            birth_year: normalizeString(person.fields.birth_year),
+            birth_year: normalizeBirthYear(person.fields.birth_year),
             gender: normalizeString(person.fields.gender)
         })
 
@@ -257,9 +291,14 @@ function transformFixtures(fixtures, report) {
             continue
         }
 
+        const name = normalizeString(transport.fields.name)
+        if (!hasMandatoryValue(name, 'Starship', 'name', ship.pk, report)) {
+            continue
+        }
+
         pushRow(rows.Starship, dedupe.Starship, {
             ID: ship.ID,
-            name: normalizeString(transport.fields.name),
+            name,
             model: normalizeString(transport.fields.model),
             starship_class: normalizeString(ship.fields.starship_class),
             manufacturer: normalizeString(transport.fields.manufacturer),
@@ -296,9 +335,14 @@ function transformFixtures(fixtures, report) {
             continue
         }
 
+        const name = normalizeString(transport.fields.name)
+        if (!hasMandatoryValue(name, 'Vehicles', 'name', vehicle.pk, report)) {
+            continue
+        }
+
         pushRow(rows.Vehicles, dedupe.Vehicles, {
             ID: vehicle.ID,
-            name: normalizeString(transport.fields.name),
+            name,
             model: normalizeString(transport.fields.model),
             vehicle_class: normalizeString(vehicle.fields.vehicle_class),
             manufacturer: normalizeString(transport.fields.manufacturer),
@@ -328,9 +372,14 @@ function transformFixtures(fixtures, report) {
 
     for (const specie of species) {
         const homeworld = resolveReference(planetsByPk, specie.fields.homeworld, `Species.homeworld(${specie.pk})`, report)
+        const name = normalizeString(specie.fields.name)
+        if (!hasMandatoryValue(name, 'Species', 'name', specie.pk, report)) {
+            continue
+        }
+
         pushRow(rows.Species, dedupe.Species, {
             ID: specie.ID,
-            name: normalizeString(specie.fields.name),
+            name,
             classification: normalizeString(specie.fields.classification),
             designation: normalizeString(specie.fields.designation),
             eye_colors: normalizeString(specie.fields.eye_colors),
@@ -363,10 +412,15 @@ function transformFixtures(fixtures, report) {
             continue
         }
 
+        const title = normalizeString(film.fields.title)
+        if (!hasMandatoryValue(title, 'Film', 'title', film.pk, report)) {
+            continue
+        }
+
         pushRow(rows.Film, dedupe.Film, {
             ID: film.ID,
             producer: normalizeString(film.fields.producer),
-            title: normalizeString(film.fields.title),
+            title,
             episode_id: Number.parseInt(film.fields.episode_id, 10) || 0,
             director: normalizeString(film.fields.director),
             release_date: normalizeDate(film.fields.release_date),
@@ -569,6 +623,8 @@ module.exports = {
     __internals: {
         normalizeString,
         normalizeDate,
+        normalizeBirthYear,
+        hasMandatoryValue,
         deterministicId,
         deterministicLinkId,
         parseArgs,