Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[TASK] Overhaul local editing #377

Merged
merged 7 commits into from
Jan 27, 2024
Merged

[TASK] Overhaul local editing #377

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d6310b1
[TASK] Overhaul local editing
linawolf Jan 26, 2024
77c6692
Apply suggestions from code review
linawolf Jan 26, 2024
8e73700
Update Documentation/WritingDocsOfficial/LocalEditing.rst
linawolf Jan 26, 2024
2edf2c6
Update Documentation/WritingDocsOfficial/LocalEditing.rst
linawolf Jan 26, 2024
593a217
Apply suggestions from code review
linawolf Jan 26, 2024
3a5f2f7
Update Documentation/WritingDocsOfficial/LocalEditing.rst
brotkrueml Jan 27, 2024
c1e0bce
Update Documentation/WritingDocsOfficial/LocalEditing.rst
brotkrueml Jan 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 78 additions & 72 deletions Documentation/WritingDocsOfficial/LocalEditing.rst
View file
Open in desktop
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
Loading