# Migrating a TopLogic application from 8.0.0-alpha4 to 8.0.0-alpha5

Audience: an AI coding agent (or developer) upgrading a TopLogic application project.
Sources: release notes https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha5/ and the
TopLogic Trac tickets of milestone `TL_8.0.0-alpha5` (ticket numbers are given as `#NNNNN`; the
per-ticket page is `https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha5/NNNNN/`).

8.0.0-alpha5 has one migration topic besides the version bump: TL-Script converts numbers to text
without locale-dependent formatting (#29064, section 4.1), and the Java method
`ToString.toString(Object)` is gone (section 1.2). It is relevant only for applications that show
numbers as text via TL-Script and rely on the user's locale for their formatting, or that call
`ToString.toString` from Java.

## How to use this document

1. Do the version bump (section 1.1). Every step has a **Detect** line: run the search in the
   application's source tree. If it finds nothing, the step does not apply — skip it. Do not invent
   changes for steps that do not apply.
2. The Java API change (section 1.2) shows up as a compile error. The changed number formatting
   (section 4.1) shows up only at runtime, as differently formatted numbers in labels, tooltips,
   columns and texts.
3. Section 7 lists behavior changes for information only; they need no change in the application.
4. For background on an engine feature, read the developer articles shipped with the engine
   (tl-mcp `list_docs` / `read_doc`).
5. Finish with the verification checklist (section 8).
6. Ticket descriptions on Trac are partly German; this document translates the relevant content.

Search commands below assume the project root as working directory and GNU grep.

---

## 1. Build and platform

### 1.1 Version bump — mandatory
Set the TopLogic version to `8.0.0-alpha5` (parent `tl-parent-app` / `tl-parent-core` version, or
the `tl.version` property).

Detect:
```
grep -rn --include=pom.xml -e '8.0.0-alpha4' .
```

### 1.2 `ToString.toString(Object)` removed (#29064) — mandatory where applicable
The Java method `com.top_logic.model.search.expr.ToString.toString(Object)` no longer exists. Use
`com.top_logic.model.search.expr.SearchExpression.asString(Object)` (now `static`) instead. Note that
`asString` formats numbers without the user's locale (section 4.1).

Before:
```java
String text = ToString.toString(value);
```
After:
```java
String text = SearchExpression.asString(value);
```

Detect:
```
grep -rn -e 'ToString.toString' --include=*.java .
```

---

## 4. TL-Script in views and layouts

### 4.1 Number-to-text conversion no longer locale-dependent (#29064) — mandatory where applicable
The conversion of values to text in TL-Script is unified (`SearchExpression.asString`). Numbers are
no longer formatted according to the user's language, but without thousands separators and with a
decimal point; integral values are written without decimal places (`1234.5` instead of `1.234,5`,
`2019` instead of `2.019`).

Affected are:
- the function `toString(...)`,
- string concatenation with `+`,
- `join(...)`,
- label, tooltip, icon and column providers defined in TL-Script (`LabelProviderByExpression`,
  `TooltipProviderByExpression`, `IconProviderByExpression`, `ComputedColumnProviderByExpression`),
- `InstanceResolverByExpression`.

Where a locale-dependent representation is needed, format the number explicitly.

Before (number shown as `1.234,5` for a German user):
```
"Total: " + $total
```
After:
```
"Total: " + numberFormat("#,##0.00").format($total)
```

Check every hit that converts a number to text; leave expressions that work with strings, objects
or dates unchanged. Expressions configured in-app (stored in the database or in overlay files of
the running application) are not found by the search; ask the user whether such configurations
exist.

Detect:
```
grep -rn -e 'toString(' -e 'ByExpression' -e 'join(' --include=*.xml .
```

---

## 7. Further notes (no action required)

### 7.1 TL-Script: database query optimization with parameters (#29064)
A filter over `all(...)` that the engine turns into a database query is now also optimized when it
is moved into a function and called with a parameter, e.g.
```
calcValue = id -> {
    all(`myModule:myType`).filter(x -> $x.get(`myModule:myType#id`) == $id)
};
$calcValue("4711")
```
Previously only the form with a literal value was optimized. Results are unchanged; such
expressions (e.g. in REST endpoints with parameters) just run faster.

### 7.2 Generator errors are marked as errors in the build output (#29292)
The output of the Java binding generation (`tl-maven-plugin:generate-java`) now prefixes each line
with `[ERROR]` or `[INFO]`, so the actual cause of a failed generation can be found in the Maven
log. In addition, an error while writing a messages file of the generated bindings now aborts the
generation; previously it was only logged and the build reported success with a missing file.

### 7.3 Known issue in 8.0.0-alpha5: optimized queries with transient objects (#29340)
A TL-Script expression that is optimized into a database query (section 7.1) fails in 8.0.0-alpha5
when a transient object is passed as a parameter (follow-up of #29064). This is fixed in
8.0.0-alpha6; no workaround is required in the application.

### 7.4 Bug fixes
- Attributes with a fallback value on transient objects (#29304): a value set on a transient
  object (e.g. in the detail dialog of a composition row) is now stored where it is read again and
  is taken over into the row object.
- Configured TL-Script functions (#29305): defining a function in the service editor with a
  description in only one language no longer fails with a `NullPointerException`.
- Undo (#29314): reverting changes whose commit message is a literal text (e.g. set by an
  application-specific undo button) no longer fails with
  `UnsupportedOperationException: Must not resolve literal text as key`.
- Change log (#29318): the change set analysis no longer fails with a `NullPointerException` when a
  created object belongs to a non-versioned type.

---

## 8. Verification checklist

1. `mvn clean install` of the application (with tests if possible). If the Java binding generation
   fails, search the build log for `[ERROR]` lines of the generator (section 7.2).
2. Start the application and read the startup log for configuration and migration errors.
3. Log in and open every view of the application; check that numbers in labels, tooltips, table
   columns and generated texts are formatted as intended (section 4.1).
4. Report to the user every step that was skipped or needed a decision, and every TL-Script
   expression changed for section 4.1.
