# Migrate Documentation ¶

Since May 29th 2019 a new infrastructure is in place at docs.typo3.org. This requires some migration tasks, in order to ensure that extension documentation is rendered on docs.typo3.org

## Necessary Steps ¶

1. Add mandatory  composer.json  , see composer.json

This file is necessary, in order to determine required information, like vendor, package name and supported TYPO3 version.

2. Add  Documentation/Settings.cfg  , see Settings.cfg

If this file does not exist, documentation will get rendered, but title will not be displayed in the left sidebar.

This requirement may be dropped in the future.For now it is necessary to at least add a minimal  Documentation/Settings.cfg  .

Example for very minimal Settings.cfg, for full example see Settings.cfg :

[general]

project = Extension name
release = latest

3. Add new webhook, see Webhook

The legacy webhook is no longer necessary, as explained in Legacy webhook . Instead the new webhook has to be added as described at Webhook .

In case the old hook is in play, remove it first, and add the new one instead.

4. Request redirects

Inform the TYPO3 Documentation Team, within #typo3-documentation Slack channel. Registration for Slack is available at my.typo3.org . Alternatively, a redirect can be requested by commenting in this GitHub issue .

The team will setup the redirects from existing legacy rendering to current rendering:

• legacy URL:  https://docs.typo3.org/typo3cms/extensions/<extkey>/<version>/ 
• new URL:  https://docs.typo3.org/p/<vendor>/<package>/<branch>/<locale> 

### Extension Release ¶

The TER (TYPO3 Extension Repository) will no longer trigger documentation rendering. Therefore uploading an extension at extensions.typo3.org does not automatically trigger rendering anymore.

In order to release a new version of an extension:

1. Publish the extension at https://extensions.typo3.org/
3. Tag the Git commit with a valid version.
4. Publish the extension at https://packagist.org/ (This is done by Webhook + Tagging)

### Version Numbers ¶

There is no change necessary. https://docs.typo3.org/ does no longer show three level version numbers in form of  Major.Minor.Patch  . Only the first two levels are shown  Major.Minor  .

This reduces the amount of documentation while keeping relevant information, as patch levels should not introduce breaking changes or new features.

### Supported branches ¶

The rendering supports two branches within repositories:

 master 
Should contain the current development state, used for upcoming release. Every push to this branch triggers a new rendering, available at  https://docs.typo3.org/p/<vendor>/<package>/master/en-us/  .
 documentation-draft 

Should contain a draft of the documentation. Every push to this branch triggers a new rendering, available at  https://docs.typo3.org/p/<vendor>/<package>/draft/en-us/  (same URL as master, except master is replaced by draft ).

This is not indexed by search engines. This branch can be used to test rendering before releasing a new version of an extension.

In order to test a different rendering, remove the branch, and create it again.

### Existing Documentation ¶

Existing legacy documentation is kept until end of 2020. Each documentation contains an information block that it’s outdated, together with a link to the necessary steps.

In order to migrate, follow Migrate Documentation . The Documentation Team can setup redirects for old documentation to new documentation afterwards. Send a message within Slack #typo3-documentation .

### URL Structure ¶

The URL structure has changed. Redirects are in place.

The URL structure now consists of the following parts:

 https://docs.typo3.org/<type>/<vendor>/<package>/<version>/<locale> 

 type 

One of:

 p 
Provides documentation for composer packages (TYPO3 third party extensions)
 c 
Provides documentation for TYPO3 core extensions.
 m 
Provides official manuals (guides, tutorials, references).
 h 
Provides the homepage of docs.typo3.org
 other 
Provides further documentation, e.g. for Surf or Fluid
 vendor 
Collects all packages of the same vendor, e.g. “typo3” or a company providing extensions. Same as on packagist.org.
 package 
Defines the package. Same as on packagist.org.
 version 
Defines the version, either in form of “Major.Minor” or  master  or  draft  .
 locale 
Defines the locale, e.g.  en-us  or  fr-fr  .