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

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-alpha4/ and the
TopLogic Trac tickets of milestone `TL_8.0.0-alpha4` (ticket numbers are given as `#NNNNN`; the
per-ticket page is `https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha4/NNNNN/`).

8.0.0-alpha4 has three migration topics besides the version bump:

- the switch of the source and resource encoding from ISO-8859-1 to UTF-8 (#29286, section 1.2) —
  relevant for every application that has non-ASCII characters in its Java sources or
  `.properties` files;
- new parameters in the TL-Script function `tree(...)` of flow diagrams (#29267, section 4.1) —
  relevant only for calls that pass `cssClass` or `userObject` positionally;
- the reorganized resource provider classes (#28388, section 5.1) — relevant only for
  applications with Java subclasses of `AbstractTLItemResourceProvider` or
  `WrapperResourceProvider`.

## How to use this document

1. Work through the sections in order. 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. Encoding problems (section 1.2) show up as compiler warnings/errors about unmappable characters
   and as broken umlauts in the UI (labels from resource bundles). Java API changes (section 5.1)
   show up as compile errors. A wrong positional `tree(...)` argument (section 4.1) shows up only
   when the flow diagram is rendered (wrong layout or a conversion error for the argument).
3. For background on an engine feature, read the developer articles shipped with the engine
   (tl-mcp `list_docs` / `read_doc`).
4. Section 7 lists behavior changes for information only; they need no change in the application.
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-alpha4` (parent `tl-parent-app` / `tl-parent-core` version, or
the `tl.version` property).

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

### 1.2 Source and resource encoding ISO-8859-1 → UTF-8 (#29286) — mandatory where applicable
The engine switched its source encoding from ISO-8859-1 to UTF-8:

- `project.build.sourceEncoding` is now `UTF-8` in the engine parent POMs (`tl-parent-all`,
  `tl-parent-build`); an application inheriting from `tl-parent-app` / `tl-parent-core` compiles
  its Java sources as UTF-8 unless it overrides the property.
- The engine reads and writes resource bundles (`WEB-INF/conf/resources/*.properties`, generated
  `META-INF/messages_*.properties`) as UTF-8. An ISO-8859-1 encoded bundle with umlauts shows
  broken characters at runtime.
- The doclet that generates `messages_*.properties` writes UTF-8 without `\uXXXX` escapes; the
  normalize goals (`tl:normalize`, `tl:normalize-resource-file`) also replace remaining `\uXXXX`
  escapes in hand-written bundles by the real UTF-8 characters.

An application with non-ASCII characters in ISO-8859-1 encoded `.java` or `.properties` files must
convert them. The new Maven goal `migrate-to-utf8` does this in one run:

1. Commit or stash local changes first — the goal writes files directly.
2. Do the version bump (step 1.1) first; the goal is inherited from `tl-parent-app` with the new
   parent version, no plugin version is needed on the command line.
3. Optionally preview:
   ```
   mvn tl:migrate-to-utf8 -DdryRun=true
   ```
4. Run:
   ```
   mvn tl:migrate-to-utf8
   ```
   If the application does not inherit from a TopLogic parent POM (prefix `tl` not resolvable),
   use the full coordinates:
   ```
   mvn com.top-logic:tl-maven-plugin:8.0.0-alpha4:migrate-to-utf8
   ```
5. `mvn install`.
6. In Eclipse, close and reopen `.properties` editors that were open, so that the encoding is no
   longer "determined from content type".

The goal performs four steps:

| Phase | What it does |
|---|---|
| Source files | Converts `.java` and `.properties` files from ISO-8859-1 to UTF-8. Pure ASCII files stay unchanged; files that already decode as valid UTF-8 are skipped and listed as *already-utf8* in the report (check them: intended UTF-8 or existing mojibake); real ISO-8859-1 files are rewritten as UTF-8. |
| POMs | Changes `project.build.sourceEncoding` from `ISO-8859-1` to `UTF-8` in every `pom.xml`. |
| Eclipse prefs | In `.settings/org.eclipse.core.resources.prefs`: sets `encoding/<project>`, `encoding/src`, `encoding//src/main/java` and `encoding//src/test/java` to `UTF-8`, removes obsolete `=ISO-8859-1` overrides. |
| Eclipse `.properties` overrides | Adds an `encoding//<path>=UTF-8` line for every `.properties` file found (Eclipse's Java-properties content type defaults to ISO-8859-1; only file-level overrides win against it). |

Parameters:

| Parameter | Meaning |
|---|---|
| `-DbaseDir=<path>` | Target directory (default: project directory / current directory). |
| `-Dextensions=java,properties[,xml,...]` | File extensions to convert (default `java,properties`). |
| `-DdryRun=true` | Report only, do not write. |
| `-DskipSources=true` / `-DskipPoms=true` / `-DskipEclipse=true` | Skip a single phase. |

After the run, check the *already-utf8* list of the report and the diff of a few converted files
(umlauts must be intact). Values with umlauts in the application's own `.properties` files are now
stored as real UTF-8 bytes instead of `\uXXXX` escapes.

Detect (any hit means the step applies):
```
grep -rn --include=pom.xml -i 'sourceEncoding>ISO-8859-1' .
LC_ALL=C grep -rlP '[\x80-\xFF]' --include=*.java --include=*.properties . | grep -v '/target/'
grep -rn 'ISO-8859-1' --include=org.eclipse.core.resources.prefs .
```
The second command lists every file with non-ASCII bytes, also files that are already UTF-8; the
goal tells them apart.

---

## 4. TL-Script in views and layouts

### 4.1 Flow diagrams: new parameters of `tree(...)` (#29267) — mandatory where applicable
The TL-Script function `tree(...)` (flow diagrams, `TreeLayout`) has the new parameters
`childSplitThreshold`, `rowWise`, `subGridCols`, `subGridStartCol` and `bridgeGapY`. They are
inserted **before** `cssClass` and `userObject`. The full parameter order is now:

| # | Parameter | # | Parameter |
|---|---|---|---|
| 1 | `nodes` | 11 | `parentAlign` |
| 2 | `connections` | 12 | `parentOffset` |
| 3 | `gapX` | 13 | `childSplitThreshold` (new) |
| 4 | `gapY` | 14 | `rowWise` (new) |
| 5 | `sibblingGapY` | 15 | `subGridCols` (new) |
| 6 | `subtreeGapY` | 16 | `subGridStartCol` (new) |
| 7 | `direction` | 17 | `bridgeGapY` (new) |
| 8 | `stroke` | 18 | `cssClass` (was 13) |
| 9 | `strokeWidth` | 19 | `userObject` (was 14) |
| 10 | `compact` | | |

Calls that pass `cssClass` or `userObject` positionally (13th or 14th argument) must switch to
named arguments. Calls with at most 12 positional arguments and calls that already use named
arguments are not affected.

Before:
```
tree($nodes, $connections, 40, null, null, null, null, "black", 1, false, 0.5, 0, "my-tree")
```
After:
```
tree($nodes, $connections, 40, null, null, null, null, "black", 1, false, 0.5, 0, cssClass: "my-tree")
```
or shorter, e.g. `tree($nodes, $connections, cssClass: "my-tree")`.

Detect (then check each hit for 13 or more positional arguments):
```
grep -rn -e 'tree(' --include=*.xml . | grep -v -i -e 'subtree(' -e '[a-z]tree('
```

---

## 5. Classic UI / Java annotations / other APIs

### 5.1 Resource providers: logic moved to `DefaultResourceProvider` (#28388) — mandatory where applicable
The label and tooltip logic of `com.top_logic.knowledge.gui.WrapperResourceProvider` and
`com.top_logic.knowledge.gui.AbstractTLItemResourceProvider` (tooltip format, label from the ID
column or the `name` attribute) moved up into `com.top_logic.mig.html.DefaultResourceProvider`.
Existing subclasses keep working; for untyped legacy persistent objects without `tType()` there is
a fallback to `TLNamed.getName()`.

Changed signatures for subclasses of `AbstractTLItemResourceProvider`:

| Before | After |
|---|---|
| `getLabel(Object)` abstract | not abstract any more (inherited from `DefaultResourceProvider`) |
| `public final String getDefaultLabel(Object)` | removed — call `super.getLabel(object)` instead |
| `public final String getTooltip(Object)` | removed from this class; `DefaultResourceProvider.getTooltip(Object)` can now be overridden |
| `protected ResKey getTooltipNonNull(Object)` | moved to `DefaultResourceProvider` (still `protected`) |
| `protected static quote(Object)` / `quote(String)` | moved to `DefaultResourceProvider` (still `protected static`) |

`WrapperResourceProvider.getLabel(Object)` is removed; its behavior (ID column, `name` attribute)
is provided by `DefaultResourceProvider.getLabel(Object)`. A `super.getLabel(object)` call in a
subclass keeps compiling and behaves as before.

Steps:
- Replace calls of `getDefaultLabel(x)` by `super.getLabel(x)`.
- A subclass that only implemented `getLabel(Object)` to reproduce the default (ID column / `name`)
  can drop the override.
- Imports of `quote`/`getTooltipNonNull` via the old class need no change as long as the subclass
  still extends `AbstractTLItemResourceProvider` (they are inherited).

Before:
```java
@Override
public String getLabel(Object object) {
    String label = getDefaultLabel(object);
    ...
}
```
After:
```java
@Override
public String getLabel(Object object) {
    String label = super.getLabel(object);
    ...
}
```

New, no action needed: the model annotations `<label>` (`TLLabel`, `label-provider`, e.g.
`LabelProviderByExpression`) and `<tooltip>` (`TLTooltip`, `tooltip-provider`, e.g.
`com.top_logic.model.search.providers.TooltipProviderByExpression`) define label and tooltip of a
type's instances in the model editor without a Java resource provider. In the `<label>` annotation
only implementations with classifier `label-provider` can be chosen.

Detect:
```
grep -rn -e 'AbstractTLItemResourceProvider' -e 'WrapperResourceProvider' -e 'getDefaultLabel(' --include=*.java .
```

---

## 7. Further notes (no action required)

### 7.1 `tUpdate` / `tAdd` / `tRemove` check loosened again (#29240)
8.0.0-alpha3 rejected writing an attribute that does not belong to the object's type. 8.0.0-alpha4
loosens this check: an attribute of a subtype that **overrides** an attribute of the object's type
may again be used to access the value, e.g. with `B extends A` and `B#part` overriding `A#part`,
`new(`A`).set(`B#part`, $value)` works (needed e.g. when copying values to an instance of a
super type). Writing an attribute of an unrelated type that merely shares the name (e.g.
`Medicine#code` on a `Door`) remains forbidden.

### 7.2 Default label and tooltip of model objects (#28388)
`DefaultResourceProvider` (and thus `MetaResourceProvider`) now determines the label of a
`TLObject` from its type: `<label>` annotation, then `<id-column>` annotation, then the `name`
attribute, else "Object without name (<type>)". The tooltip comes from the `<tooltip>` annotation,
else the previous format "<label> (<type>)". Annotations are inherited along the primary
generalization chain and can be overridden in a subtype.

### 7.3 Failed checks are no longer reported as "internal error" (#29249)
A model constraint ("check") that fails on save is now shown as a validation message instead of an
"Internal error" box, and is no longer logged as an ERROR.

### 7.4 Change log: subtree filter, undo/redo (#29236)
New: TL-Script functions `changeLog(...)` and `revertChanges(...)`, command handlers
`UndoCommandHandler` / `RedoCommandHandler`, the utility `ChangeSetReverter`. The type
`tl.changelog:ChangeSet` gets the derived attributes `isRevert` and `isRedo`; the engine's
automatic migration `Ticket_29236_Added_isRevert_isRedo` adds them to the model on the first start.

### 7.5 Browser tab title (#29262)
The title of the browser tab can now be set via `<page-title>` at the `MainLayout`, via the
component resolvers `DynamicPageTitle` / `TabPageTitle`, or via the new property *Page title* in
the layout editor. Without configuration the title stays as before.

### 7.6 Flow diagram tree layout (#29267)
The new `tree(...)` parameters (section 4.1) lay out nodes with many children in a 2D sub-grid
(column-wise, or row-wise with `rowWise`). The default `childSplitThreshold` = 0 keeps the previous
layout.

---

## 8. Verification checklist

1. `mvn clean install` of the application (with tests if possible). There must be no compiler
   warnings about unmappable characters for encoding UTF-8.
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 labels with umlauts from the
   application's resource bundles display correctly, and that object labels and tooltips look as
   before (or as configured).
   Open every view with a flow diagram built by `tree(...)` and check its layout and styling
   (section 4.1).
4. Report to the user every step that was skipped or needed a decision, the *already-utf8* list of
   `tl:migrate-to-utf8`, and every file in which the encoding conversion changed characters other
   than the expected umlauts.
