From d6310b13366bfcbc0475145de878fe85243dc612 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Fri, 26 Jan 2024 17:26:48 +0100 Subject: [PATCH 1/7] [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 --- .../WritingDocsOfficial/LocalEditing.rst | 149 +++++++++--------- 1 file changed, 77 insertions(+), 72 deletions(-) diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index 314b1f9d..70fbd4b5 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -3,111 +3,116 @@ .. 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 GitHub +============================================================= + +You can clone the Git repository with a manual to your computer and +`preview the rendered result locally `. + +The official manuals of the documentation team can be found in the organization +`TYPO3-Documentation on GitHub `__. 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 `__ 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 `__ 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) as 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 documentations repository in 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//.git + .. code-block:: bash + git clone https://github.com//.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 `__ - and `email `__ - (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 `__ + Setup `username `__ + and `email `__ + (if not already setup in your global :file:`~/.gitconfig`). -5. Create a branch for your changes + `Setup your .ssh key for GitHub `__ +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 instead using 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 ` 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 ` to help get you 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 + word your commit messages. -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 @@ -131,11 +136,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 ================================== @@ -157,15 +162,15 @@ You local repository is based on the forked repository in your workspace. For example, -* URL of fork: `git@github.com:/TYPO3CMS-Guide-HowToDocument.git` -* original URL: `git@github.com:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git` +* URL of fork: `git@github.com:/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: -.. code-block:: bash +.. code-block:: bash - git pull origin main + git pull origin main because origin points to your fork. @@ -175,10 +180,10 @@ Do it now You must now do the following: -.. code-block:: bash +.. code-block:: bash - git remote add upstream git@github.com:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git - git pull upstream main + git remote add upstream git@github.com:TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git + git pull upstream main Replace the URI with the correct URI for the original repository, not your fork! @@ -186,9 +191,9 @@ 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. @@ -199,8 +204,8 @@ More information For more information in this guide: -* :ref:`Formatting-with-reST` -* `Rendering Documentation With Docker `__ +* :ref:`Formatting-with-reST` +* :ref:`Rendering documentation with Docker ` For more information about GitHub see the help pages on GitHub or other From 77c6692c7cc20a63e914728b75b844adc8d72645 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 18:01:30 +0100 Subject: [PATCH 2/7] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- .../WritingDocsOfficial/LocalEditing.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index 70fbd4b5..df0b13b9 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -7,7 +7,7 @@ Workflow #2: Working locally on the documentation with GitHub ============================================================= -You can clone the Git repository with a manual to your computer and +You can clone the Git repository of a manual to your computer and `preview the rendered result locally `. The official manuals of the documentation team can be found in the organization @@ -31,7 +31,7 @@ the ability to experiment and preview your changes locally before submitting the In the footer of the documentation you wish to make changes to, select the :guilabel:`Repository` link. - This will take you to the documentations repository in GitHub. + This will take you to the documentation's repository in GitHub. From here, select the "Fork" button in the upper right corner of the page. @@ -50,15 +50,15 @@ the ability to experiment and preview your changes locally before submitting the git clone https://github.com//.git -4. Setup Git Settings and SSH Key +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 :file:`~/.gitconfig`). + (if not already setup in your global :file:`~/.gitconfig` file). - `Setup your .ssh key for GitHub `__ + `Setup your ssh key for GitHub `__ 5. Create a branch for your changes @@ -66,9 +66,9 @@ the ability to experiment and preview your changes locally before submitting the 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 + #. 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`. + #. Always branch from `main`. If you are checked in to a feature branch, switch back to `main` first: @@ -104,7 +104,8 @@ the ability to experiment and preview your changes locally before submitting the 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. + word your commit messages. Please also add links to resources which might be useful + for a reviewer to know (when appropriate). 9. Push changes From 8e73700e71db9c0a44a8d6db3b72e9be8818a97f Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 18:02:26 +0100 Subject: [PATCH 3/7] Update Documentation/WritingDocsOfficial/LocalEditing.rst --- Documentation/WritingDocsOfficial/LocalEditing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index df0b13b9..becfd50f 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -3,9 +3,9 @@ .. index:: Official documentation; Local editing .. _docs-contribute-git-docker: -============================================================= -Workflow #2: Working locally on the documentation with GitHub -============================================================= +========================================================== +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 `. From 2edf2c6309cea3c79aff413a4c7bb6a6fd6d6ee4 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 18:02:51 +0100 Subject: [PATCH 4/7] Update Documentation/WritingDocsOfficial/LocalEditing.rst --- Documentation/WritingDocsOfficial/LocalEditing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index becfd50f..6e3b657c 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -64,7 +64,7 @@ the ability to experiment and preview your changes locally before submitting the .. 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 instead using 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`. From 593a2178bcd2e57a474568c415093c8f397c4a6c Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Fri, 26 Jan 2024 21:33:53 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Garvin Hicking --- Documentation/WritingDocsOfficial/LocalEditing.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index 6e3b657c..05b6c541 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -24,14 +24,14 @@ the ability to experiment and preview your changes locally before submitting the 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. + to set your GitHub name (*not* username) to your full name. 2. Find and fork the repository In the footer of the documentation you wish to make changes to, select the :guilabel:`Repository` link. - This will take you to the documentation's repository in GitHub. + This will take you to the documentation's repository on GitHub. From here, select the "Fork" button in the upper right corner of the page. @@ -104,7 +104,7 @@ the ability to experiment and preview your changes locally before submitting the 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. Please also add links to resources which might be useful + phrase your commit messages. Please also add links to resources which might be useful for a reviewer to know (when appropriate). 9. Push changes From 3a5f2f76b9b25b2905d58db1ccc72f99bb97a9fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Sat, 27 Jan 2024 06:38:18 +0100 Subject: [PATCH 6/7] Update Documentation/WritingDocsOfficial/LocalEditing.rst --- Documentation/WritingDocsOfficial/LocalEditing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index 05b6c541..4b9e228c 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -64,7 +64,7 @@ the ability to experiment and preview your changes locally before submitting the .. 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`. From c1e0bce023b7114709930fa5bea5c729796fe1c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Chris=20M=C3=BCller?= <2566282+brotkrueml@users.noreply.github.com> Date: Sat, 27 Jan 2024 06:39:30 +0100 Subject: [PATCH 7/7] Update Documentation/WritingDocsOfficial/LocalEditing.rst --- Documentation/WritingDocsOfficial/LocalEditing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/WritingDocsOfficial/LocalEditing.rst b/Documentation/WritingDocsOfficial/LocalEditing.rst index 4b9e228c..e1aca07b 100644 --- a/Documentation/WritingDocsOfficial/LocalEditing.rst +++ b/Documentation/WritingDocsOfficial/LocalEditing.rst @@ -87,7 +87,7 @@ the ability to experiment and preview your changes locally before submitting the 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 ` to help get you started + :ref:`reST Introduction ` to get started along with the :ref:`rest-cheat-sheet`. 7. Render the documentation