Review main Merged

83588[DOCS] Switch changelog documentation to PHP-based rendering

Lina Wolf CR +2 V +2 Normal +24 −100 updated 03/26/24, 13:10

Commit message

You can try out the rendering locally with

```
cd typo3/sysext/core
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
```

Review

  • Code review CR +2 Done
    • Lina Wolf +2
    • Garvin Hicking +1
    • Benni Mack +1
  • Verified V +2 Done
    • Lina Wolf +2
    • Benni Mack +1
    • core-ci +1 CI

Issues 1

Files 3

Review log 67

  1. Lina Wolf uploaded patch set 1 03/25/24, 17:39

  2. core-ci voted on patch set 1 V +1 03/25/24, 17:45 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/54933

  3. Benjamin Franzke commented on patch set 1 03/25/24, 18:17

    Will you provide semantic versions for the `documentation/render-guides` container image? That would be important for running in CI against a defined Major.Minor version (in order to be able to run older patches/branches against the known working major:minor, in case of bisecting or so) I guess that would currently be `0.2` according to https://github.com/TYPO3-Documentation/render-guides/releases We should refer to that (ideally withing this commit, so it's clear with which version this render config was introduced).
    works with `podman run` as well 👍 We should therefore suggest to use podman instead of docker for security reasons (as podman runs as user, while docker will run as root and therefore has to drop privileges to prevent writing as root). Using `podman` instead of `docker` would allow to remove workarounds like https://github.com/TYPO3-Documentation/render-guides/blob/main/entrypoint.sh#L90-L132 With podman the uid=0 is always mapped to the current user automatically, as the entiree container runs as user. Therefore local-user=container-root => no `chown`/`su` workarounds needed Ideally we would add this command to runTests.sh, but it's fine to do that in a follow-up PR, cc @stefan@buerk.tech
  4. Garvin Hicking commented on patch set 1 CR +1 03/26/24, 07:57

    Some answers to Benjamin, I hope it's okay I see those as resolved. Please re-open if you see it differently. (I couldn't check the ChangeLog rendering myself for "proper rendering", so can't yet vote on this.)

    Reply

    In the Docs to render-guides we do mention podman is an option (https://github.com/TYPO3-Documentation/render-guides/pull/391) Since the rendering container is aimed to work across all platforms so it can be used by any extension developer, we did not want to add additional weight by requiring/strongly suggesting a tool like podman, so we would need the entrypoint-docker-thing to keep it working for docker, when people don't really understand what alternate Docker providers/clients/engines are (I myself don't fully grasp what does what with Orbstack, Colima, Podman and whathaveyou). I talked with Stefan about it, and yes, for the runTests integration we would utilize the chose "engine" to use there!

    Reply

    Currently we are not "feature-frozen" and there is still a lot of ongoing work. However, we can't finish the process unless we start switching the moving parts to the new container. Our docker build process does use tags and we plan to use semver for it. Ideally we don't want to maintain different major versions next to each other, so for extension developers we always recommend to use "latest". Also we plan to prevent breaking changes, or add automatic migration paths, so that you should always be able to render documentation with "latest". So for now, for us to be able to fix things without fixing dependant code, it would really help to use "latest" for now. Actually, the place were rendering takes place (intercept/gh-render-action) is the place where we ourselves maintain the version that is used. So this commit doesn't actually introduce code that locks the version on its own. Integrating it into runTests with Stefan, however, we do need to take care of that for sure, but with the scope of a seperate PR.
  5. Benni Mack voted on patch set 1 CR +1 V +1 03/26/24, 13:08

  6. Lina Wolf voted on patch set 1 CR +2 V +2 03/26/24, 13:10

  7. Lina Wolf merged patch set 2 03/26/24, 13:10