Skip to content

Commit

Permalink
[TASK] Overhaul local editing (#377)
Browse files Browse the repository at this point in the history 
* [TASK] Overhaul local editing

Correct the headline, this is really an introduction to GitHub and does not explain how to render with Docker. Link to rendering with Docker page. Correct indentation, introduce GitHub Organization as entry point

* Apply suggestions from code review

Co-authored-by: Chris Müller <[email protected]>

* Update Documentation/WritingDocsOfficial/LocalEditing.rst

* Update Documentation/WritingDocsOfficial/LocalEditing.rst

* Apply suggestions from code review

Co-authored-by: Garvin Hicking <[email protected]>

* Update Documentation/WritingDocsOfficial/LocalEditing.rst

* Update Documentation/WritingDocsOfficial/LocalEditing.rst

---------

Co-authored-by: Chris Müller <[email protected]>
Co-authored-by: Garvin Hicking <[email protected]>
  • Loading branch information
@linawolf @brotkrueml @garvinhicking
3 people authored Jan 27, 2024
1 parent 1e5eb91 commit 961d7c9
Showing 1 changed file with 78 additions and 72 deletions.
150 changes: 78 additions & 72 deletions Documentation/WritingDocsOfficial/LocalEditing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,111 +3,117 @@
.. index:: Official documentation; Local editing
.. _docs-contribute-git-docker:

======================================================
Workflow #2: "Local editing and rendering with Docker"
======================================================
==========================================================
Workflow #2: Working locally on the documentation with Git
==========================================================

You can clone the Git repository of a manual to your computer and
`preview the rendered result locally <rendering-docs>`.

The official manuals of the documentation team can be found in the organization
`TYPO3-Documentation on GitHub <https://github.com/TYPO3-Documentation>`__.

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.

.. rst-class:: bignums-xxl

1. Create a GitHub account:
.. rst-class:: bignums-xxl

Visit `Join GitHub <https://github.com/join>`__ and create your account.
1. Create a GitHub account:

Though not mandatory, the general convention in the TYPO3 community is
to set your GitHub name (*not* username) as your full name.
Visit `Join GitHub <https://github.com/join>`__ and create your account.

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

In the footer of the documentation you wish to make changes to,
select the :guilabel:`Repository` link.
2. Find and fork the repository

This will take you to the documentations repository in GitHub.
In the footer of the documentation you wish to make changes to,
select the :guilabel:`Repository` link.

From here, select the "Fork" button in the upper right corner of the page.
This will take you to the documentation's repository on GitHub.

.. image:: /Images/github-fork.png
:class: with-shadow
From here, select the "Fork" button in the upper right corner of the page.

3. Clone the forked repository
.. image:: /Images/github-fork.png
:class: with-shadow

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

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

.. code-block:: bash
In your terminal:

git clone https://github.com/<USERNAME>/<NAME OF REPOSITORY>.git
.. code-block:: bash
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:
4. Setup Git settings and SSH key

Setup `username <https://help.github.com/en/articles/setting-your-username-in-git>`__
and `email <https://help.github.com/en/articles/setting-your-commit-email-address-in-git>`__
(if not already setup in your global :file:`~/.gitconfig`).
For this, we refer to the general help on Git and GitHub:

`Setup your .ssh key for GitHub <https://help.github.com/en/enterprise/2.15/user/articles/adding-a-new-ssh-key-to-your-github-account>`__
Setup `username <https://help.github.com/en/articles/setting-your-username-in-git>`__
and `email <https://help.github.com/en/articles/setting-your-commit-email-address-in-git>`__
(if not already setup in your global :file:`~/.gitconfig` file).

5. Create a branch for your changes
`Setup your ssh key for GitHub <https://help.github.com/en/enterprise/2.15/user/articles/adding-a-new-ssh-key-to-your-github-account>`__

5. Create a branch for your changes

.. important::
.. important::

If you did not just fork and clone but are instead using an old local version of this repository:
If you did not just fork and clone, but are using instead an old local version of this repository:

#. Make sure the repository is up-to-date by pulling from upstream as described
in :ref:`contribute-edit-locally-more-changes`.
#. Always branch from `main`.
If you are checked in to a feature branch, switch back to `main`
first:
#. Make sure the repository is up-to-date by pulling from upstream as described
in :ref:`contribute-edit-locally-more-changes`.
#. Always branch from `main`.
If you are checked in to a feature branch, switch back to `main`
first:

.. code-block:: bash
.. code-block:: bash
git checkout main
git checkout main
For example, create the branch `feature/changes-in-cgl`:

.. code-block:: bash
.. code-block:: bash
git checkout -b feature/changes-in-cgl
git checkout -b feature/changes-in-cgl
6. Make your changes
6. Make your changes

Using your preferred IDE or editor you can now start making 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
:ref:`reST Introduction <writing-rest-introduction>` to help get you started
along with the :ref:`rest-cheat-sheet`.
If you are not familiar with reST, you can visit the
:ref:`reST Introduction <writing-rest-introduction>` to get started
along with the :ref:`rest-cheat-sheet`.

7. Render the documentation
7. Render the documentation

Render your changes with Docker to preview them locally:
Render your changes with Docker to preview them locally:

* :ref:`render-documenation-with-docker`
* :ref:`render-documenation-with-docker`

8. Commit
8. Commit

.. code-block:: bash
.. code-block:: bash
git commit -a
git commit -a
Write a short, meaningful commit message describing what changes you have made.
See :ref:`general-conventions-commit-messages` for more information on how to
word your commit messages.
Write a short, meaningful commit message describing what changes you have made.
See :ref:`general-conventions-commit-messages` for more information on how to
phrase your commit messages. Please also add links to resources which might be useful
for a reviewer to know (when appropriate).

9. Push changes
9. Push changes

.. code-block:: bash
.. code-block:: bash
git push origin changes-in-cgl
git push origin changes-in-cgl
This will push the change to your forked repository.
This will push the change to your forked repository.

10. Create Pull request

Expand All @@ -131,11 +137,11 @@ the ability to experiment and preview your changes locally before submitting the
Next steps
==========

* Look at :ref:`docs-official-how-you-can-help` for more ways to contribute.
* Look at :ref:`docs-official-how-you-can-help` for more ways to contribute.


.. index:: Official documentation; Fork up-to date
.. _contribute-edit-locally-more-changes:
.. index:: Official documentation; Fork up-to date
.. _contribute-edit-locally-more-changes:

Keeping your local fork up-to date
==================================
Expand All @@ -157,15 +163,15 @@ You local repository is based on the forked repository in your workspace.

For example,

* URL of fork: `[email protected]:<your username>/TYPO3CMS-Guide-HowToDocument.git`
* original URL: `[email protected]:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git`
* URL of fork: `[email protected]:<your username>/TYPO3CMS-Guide-HowToDocument.git`
* original URL: `[email protected]:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git`

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


.. code-block:: bash
.. code-block:: bash
git pull origin main
git pull origin main
because origin points to your fork.

Expand All @@ -175,20 +181,20 @@ Do it now

You must now do the following:

.. code-block:: bash
.. code-block:: bash
git remote add upstream [email protected]:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git
git pull upstream main
git remote add upstream [email protected]: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 :file:`.git/config` in your local repository,
so next time it is enough to do:

.. code-block:: bash
.. code-block:: bash
git pull upstream main
git pull upstream main
Now, continue with step 5 (create branch) in the first section of this page.
Expand All @@ -199,8 +205,8 @@ More information

For more information in this guide:

* :ref:`Formatting-with-reST`
* `Rendering Documentation With Docker <https://github.com/t3docs/docker-render-documentation/blob/main/README.rst>`__
* :ref:`Formatting-with-reST`
* :ref:`Rendering documentation with Docker <rendering-docs>`


For more information about GitHub see the help pages on GitHub or other
Expand Down

0 comments on commit 961d7c9

Please sign in to comment.