Workflow #2: “Local editing and rendering with Docker”¶
This section walks you through contributing to the documentation with Git and Docker.
If necessary, ask for help as explained in Help & Support.
This describes how to create a pull request for the TYPO3 documentation. All steps described are steps you would usually do for any GitHub pull request. Only the part about editing (step 6) and rendering (step 7) are specific to TYPO3 documentation.
Get a GitHub account:
Fill out the form on Join GitHub.
The general convention in the TYPO3 community is to use your full real name as name (not username), but it is not a requirement.
Be sure to use an email-address that you will regularly check as soon as you upload changes to GitHub.
Find and fork the repository
Find the repository for the manual you wish to make changes to. In the footer of the rendered documentation on docs.typo3.org, click on the link Repository.
This will direct you to the repository on GitHub.
There, click on the “Fork” button in the upper right.
The repository will be forked to your workspace on GitHub. You can delete it later or reuse it for further changes.
Clone the forked repository
Clone the forked repository from your workspace (click Clone or download to copy the URL).
In your terminal:
git clone https://github.com/<USERNAME>/<NAME OF REPOSITORY>.git
Setup Git Settings and SSH Key
For this, we refer to general help on Git or GitHub:
Create a branch
If you did not just fork and clone but are using a local repository, you created a while ago:
For example, create the branch
git checkout -b feature/changes-in-cgl
Using your preferred IDE or editor (see Tools for Editing reST, make changes to the files.
If you are not familiar with reST, you might want to check out reST Introduction first!
Also, see our reST & Sphinx cheat sheet in this guide.
Render the documentation
Render with Docker in order to test the changes:
git commit -a
Write a short commit message, describing what was changed, for example “Fix link”. See Commit messages, but keep in mind that the conventions for commit messages for the documentation are not strict.
git push origin changes-in-cgl
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”.
Now, wait for someone to review and merge your pull request
You will receive notifications (email) about this. Once your change is merged, you can reload the page (which you fixed) in your browser.
Congratulations! You are now a contributor. Welcome and thank you!
Keep your local fork up-to date¶
This section describes how to keep your local repository up-to-date. This is similar to the section “Keep your fork synced” on the online resource Fork a repo.
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.
- URL of fork:
- original URL:
So, running the following will not get the latest changes:
git pull origin master
because origin points to your fork.
Do it now¶
You must now do the following:
git remote add upstream firstname.lastname@example.org:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git git pull upstream master
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 master
Now, continue with step 5 (create branch) in Quick Start.