Add Documentation

Quick links:

The documentation Changelog and documentation for system extensions is maintained in the core.

Changelog

Some patches require a .rst (reStructuredText) Changelog file describing the change. Not all patches need an entry in the Changelog. Check the list below. Also see the current Changelog for some examples.

Every file may optionally contain tags, but it must contain at least a NotScanned, PartiallyScanned or FullyScanned tag for the extension scanner. See Extension scanner in TYPO3 Explained for more information.

If you use the Forger reST File Generator, it will take care of this.

reST File Generator

Tip

If you want to save yourself some time you can use the rst Helper at https://forger.typo3.com/utilities/rst

This is strongly recommended because the tool will generate correctly formatted files. You can always add more to the .rst file directly later.

Select the type of rst snippet you want to create, enter your issue number and click the search button. Select appropriate tags.

When you are done, copy the generated text and create a file with the same name as suggested in the generator.

Types of Changes

There are four different types of changes which have to follow a certain format and always need to go into typo3/sysext/core/Documentation/Changelog/<release>/.

Choose one which fits your patch:

Breaking Changes

A patch moved or removed a specific part of core functionality that may break extensions if they use this part.

Mandatory sections:

  1. Description - why things had to break backwards compatibility.

  2. Impact - how will the change affect your installation.

  3. Affected Installations - describe scenarios under which circumstances a TYPO3 install will be affected by this change.

  4. Migration - provide instructions what needs to be done to get things working again. Explicitly mention if no migration is possible.

Deprecations

A patch deprecates a certain core functionality for a planned removal. See more information: Deprecations

Mandatory sections:

  1. Description - why things had to be deprecated.

  2. Impact - how will the change affect your installation.

  3. Affected Installations - describe scenarios under which circumstances an TYPO3 install will be affected by this change.

  4. Migration - provide instructions what needs to be done to get things working again. Explicitly mention if no migration is possible.

Features

A patch adds new functionality.

Mandatory sections:

  1. Description - what can the new feature do.

  2. Impact - how users are affected by this new feature.

Important Information

Anything that does not fit the other categories but is important enough to require a Changelog entry.

  1. Description - describe what is so important it needed an rst snippet

Check Your rst File

When your change is finished, you can run the following script to check that your rst file is ok. The script will check all files in typo3/sysext/core/Documentation/Changelog:

shell command
Build/Scripts/validateRstFiles.php

This script will check if the .rst files contain all mandatory tags that are required for the Changelog. It will not do a reST syntax check.

In order to make sure that your file contains no syntax errors and will be rendered correctly, do one or more of the following:

Render the Changelog

If you wish to render the Changelog locally, you can use docker as described in How to render documentation.

shell command
 1cd typo3/sysext/core/
 2source <(docker run --rm t3docs/render-documentation show-shell-commands)
 3dockrun_t3rd makehtml
 4# on Mac
 5open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"
 6# on Linux
 7xdg-open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"
 8# On Windows
 9start "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html"
10cd -

  1. First, change to the core directory

  2. This is a combined command that does docker pull, docker run, and makes some shell commands available in current terminal!

  3. This runs the build command, it will create Documentation-GENERATED-temp in current directory

  4. open will run a URL - this should work on MacOS

  5. If you use Linux, use xdg-open, if this does not work, just open the URL in quotes in your browser.

  6. cd - goes back to previous directory

Tip

The first time you run this, it will take long. docker pull will download the Docker image. The next time, it will be faster, because the image does not have to be downloaded and dockrun_t3rd will not build everything, it will only build changed files.

Important

If you switch branches, you should rebuild everything. You can either remove the folder Documentation-GENERATED-temp/Cache and all its contents or run dockrun_t3rd makehtml-no-cache which has the same effect.

Make things easier for yourself by adding these commands as aliases or adding them as commands in your IDE / editor.

Policy for Changing the Main Documentation

Once a new TYPO3 release comes out, the main documentation (e.g. TYPO3 Explained, t3tca:start etc.) must be updated.

The procedure is documented in Update documentation for new releases.

Document System Extensions

Documentation for system extensions is maintained within a Documentation directory in the respective system extension directory, e.g. typo3/sysext/form/Documentation.

Not all system extensions have their own documentation. Some documentation (e.g. for the system extension core) is maintained within the TYPO3 Explained.

If in doubt, ask in the #typo3-cms-coredev channel on Slack.

For starting a system extension from scratch, please see How to document an extension.

For an overview of the rendered documentation for system extensions, see System Extensions.

When you have made changes to the documentation, you can render locally with docker to test your changes as described in Render the Changelog.

More Information