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.

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

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

    ../_images/github-fork.png
  3. 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
    
  4. 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

  5. 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 master (see also [IMPORTANT] Change main branches to master). If you are checked in to 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 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 reST & Sphinx cheat sheet.

  7. Render the documentation

    Render your changes with Docker to preview them locally:

  8. Commit

    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.

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

    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!

Next steps

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 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 edit-locally-quickstart.

More information

For more information in this guide:

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