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.

Quick Start

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.

1. 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.

2. Find and fork the repository

   Find the repository for the manual you wish to make changes to. On the lower left side of the rendered documentation, click on the link "Related Links". Then 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.

3. 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
   

4. Setup Git Settings and SSH Key

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

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

   Setup your .ssh key for GitHub

5. Create a branch

   重要

   If you did not just fork and clone but are using a local repository, you created a while ago:

   1. Make sure the repository is up-to-date by pulling from upstream as described in Keep Your Local Fork Up-to-date.

   2. Always branch from master (see also [IMPORTANT] Change Main Branches to master). If you have still checked out a feature branch, switch back to master first:

      git checkout master
      

   For example, create the branch feature/changes-in-cgl:

   git checkout -b feature/changes-in-cgl
   

6. Make changes

   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.

7. Render the documentation

   Render with Docker in order to test the changes:

   • Rendering Documentation with Docker (works best on Linux)
   • Rendering Documentation with Docker Compose (should work better on MacOS or Windows, but is still being tested)

8. Commit

   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.

9. Push changes

   git push origin changes-in-cgl
   

   This will push the change to your forked repository.

10. 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!

Next Steps

• Look at How You Can Help for more ways to contribute.

Keep Your Local Fork Up-to-date

Explanation

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.

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 master

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 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.

More information

For more information in this guide:

• reStructuredText & Sphinx
• Rendering Documentation With Docker

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

• Creating a pull request from a fork
• How to Create a Pull Request on GitHub
• Fork a repo