Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

Workflow #2: "Local editing and rendering with Docker"

Using your local machine instead of editing documentation on GitHub has many advantages, it includes the freedom to choose which IDE you make your changes in and it also gives you the ability to experiment and preview your changes locally before submitting them for approval.

Create a GitHub account:

Visit Join GitHub and create your account.

Though not mandatory, the general convention in the TYPO3 community is to set your GitHub name (not username) as your full name.
Find and fork the repository

In the footer of the documentation you wish to make changes to, select the Repository link.

This will take you to the documentations repository in GitHub.

From here, select the "Fork" button in the upper right corner of the page.
Clone the forked repository

Clone the forked repository from your workspace (select Clone or download to copy the URL).

In your terminal:
```
git clone https://github.com/<USERNAME>/<NAME OF REPOSITORY>.git
```
Copied!
Setup Git Settings and SSH Key

For this, we refer to the general help on Git and GitHub:

Setup username and email (if not already setup in your global ~/.gitconfig).

Setup your .ssh key for GitHub
Create a branch for your changes
Important

If you did not just fork and clone but are instead using an old local version of this repository:
1. Make sure the repository is up-to-date by pulling from upstream as described in Keeping your local fork up-to date.
2. Always branch from main. If you are checked in to a feature branch, switch back to main first:
```
git checkout main
```
  Copied!
For example, create the branch feature/changes-in-cgl:
```
git checkout -b feature/changes-in-cgl
```
Copied!
Make your changes

Using your preferred IDE or editor you can now start making your changes.

If you are not familiar with reST, you can visit the reST Introduction to help get you started along with the Cheat sheet: reStructuredText.
Render the documentation

Render your changes with Docker to preview them locally:
- Render documentation with the TYPO3 theme
Commit
```
git commit -a
```
Copied!
Write a short, meaningful commit message describing what changes you have made.
Push changes
```
git push origin changes-in-cgl
```
Copied!
This will push the change to your forked repository.
Create Pull request

Now, in your browser, visit the forked repository in your GitHub workspace. GitHub will already make some suggestions for a pull request and will display your pushed branch as "Your recently pushed branches".

Click on the green button "Compare & pull request" and then "Create pull request".

Your change will now be reviewed. A reviewer might suggest additional changes. Monitor your notifications (email) from GitHub. If at any point, you are not sure what to do, don't hesitate to ask for help. When your pull request is accepted, it will be merged. You will receive a notification email as soon as this happens.

More information on how your submissions ("PR"s, "Pull Requests") will receive feedback can be found in the chapter Policy for making and reviewing contributions.

Congratulations! You are now a contributor. Welcome and thank you!

Next steps

Look at How you can help for more ways to contribute.

Keeping your local fork up-to date

Explanation

This section describes how to keep your local repository up-to-date. This is similar to the GitHub documentation in chapter Keep your fork synced.

If you have already created a patch for a repository, you can reuse your local repository. This means you do not have to fork and clone for every new patch.

However, if you reuse your local clone, you should make sure it is up-to-date before you create another branch for a new patch.

You local repository is based on the forked repository in your workspace.

For example,

URL of fork: git@github.com:<your username>/TYPO3CMS-Guide-HowToDocument.git
original URL: git@github.com:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git

So, running the following will not get the latest changes:

git pull origin main

because origin points to your fork.

Do it now

You must now do the following:

git remote add upstream git@github.com:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git
git pull upstream main

Replace the URI with the correct URI for the original repository, not your fork!

The URL for upstream has now been written to .git/config in your local repository, so next time it is enough to do:

git pull upstream main

Now, continue with step 5 (create branch) in the first section of this page.

More information

For more information in this guide:

For more information about GitHub see the help pages on GitHub or other resources, for example: