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 (see Tools for Editing reST) 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
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
Create a branch for your changes
If you did not just fork and clone but are instead using an old local version of this repository:
Make sure the repository is up-to-date by pulling from upstream as described in Keeping your local fork up-to date.
Always branch from
main(see also [IMPORTANT] Change master branches to main). If you are checked in to a feature branch, switch back to
git checkout main
For example, create the branch
git checkout -b feature/changes-in-cgl
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: reST & Sphinx.
Render the documentation
Render your changes with Docker to preview them locally:
Rendering the documentation with Docker (works best on Linux)
Rendering the documentation with Docker Compose (should work better on MacOS and Windows, but is still in development)
git commit -a
Write a short, meaningful commit message describing what changes you have made. See Commit messages for more information on how to word your commit messages.
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".
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.
Congratulations! You are now a contributor. Welcome and thank you!
Look at How You Can Help for more ways to contribute.
Keeping your local fork up-to date¶
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.
URL of fork:
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 firstname.lastname@example.org: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.
For more information in this guide:
For more information about GitHub see the help pages on GitHub or other resources, for example: