[TASK] Add a "Quick start" tutorial for contributors (DevDays) (#345)

* [TASK] Add a "Quick start" tutorial for contributors (DevDays)

* Update indents in Quick Start

* Update typo in Visual Studio

* Update indents in 2-Accounts

* Update indents in 3-git

* Update indents in 4-ddev

* Update 1-Preqrequisites.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update 2-Accounts.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update 5-TYPO3.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update 5-TYPO3.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update 6-Patch-Intermezzo.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update 6-Patch-Intermezzo.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update 6-Patch.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update 7-Contribute.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update Index.rst

Co-authored-by: Stefan Frömken <[email protected]>

* Update 4-DDEV.rst

* Update 4-DDEV.rst

* Update 5-TYPO3.rst

* Update 7-Contribute.rst

* [TASK] Remove copy&paste left over

This change removes a copy&paste left over
from the `Quickstart/Index.rst`.

* [TASK] Modify quickguide prerequisites page

This change modifies the `Quickstart/1-Prerequisites.rst`
to add minor additional information to some points.

* [TASK] Enhance `Quickstart/Git setup guide`

This change modifes the `Quickguide/3-Git.rst` file
to enhance the experience by ...

* ensuring single commands per code block to allow block
  copy and pasting by using the block copy icon.
* using more cross operating-system compatible commands.
* note when in a command replacements are needed
* add a general tip to copy commands to a text file or
  editor to do the replacement before pasting it into a
  terminal
* add a additional verification step at the end.

* [TASK] Enhance `Quickguide: Set up DDEV` page

This change modifies `Quickstart/4-DDEV.rst` to
enhance the guide slightly.

* [TASK] Enhance `Quick Start: Set up TYPO3` chapter

This change modifies the `Quickstart/5-TYPO3.rst` file
to enhance the experience for the user proceeding this
chapter by

* ensuring to have single command or command chain to
  simply use the copy icon and have no issues pasting
  them into the terminal.
* adding generic project folder switch as note at the
  top.
* providing `EXT:styleguide` create commands creating
  the frontend based on `TypoScript records` instead
  of the Site Sets feature, which seems to be broken
  for now with ddev.
* Reworded the attention block to state the reason
  instead of leaving a to do - which looks kind of
  weired for readers.

* [TASK] Minor change of quickstart patch intermezzo

* [TASK] Enhance `Quick Start: Create a patch` chapter

This change modifies the `Create a patch` chapter
slightly to make it more easier for contributors
to create their first patch by

* ensuring single commands or proper command chains
  which can be properly copied using the copy icon
  and pasted into a terminal.
* using `:caption:` tags for `code blocks` to explain
  each command copy block itself.
* adding general remember on top to be in the right
  folder.
* adding a additional `cleanup` point at the end
  providing suitable commands and small explanation.

* [TASK] Hint for clean repository to the `patch intermezzo` chapter

This change adds a general hint to the
`Quick Start: Create a patch - Intention`
chapter raising awareness for a clean
repository state and how to deal with it
if not.

* [TASK] Sync `repository reset and cleanup` information in multiple places

This change streamlines the `reset and cleanup` steps and
information throughout multiple places to contain as much
information as possible while still beeing able to copy
single command and chains for easy copy&paste experiance.

* [TASK] Combined code review

This addresses:

* Rename "15 minutes" to "under 30 minutes"
* Streamline $HOME dir usage
* Remove some explanations that enlarge the text too much
* Remove some of the prerequisites that are needed,
  and would otherwise take up too much text. The long version
  is still part of this guide, it fits there better.
* streamline ddev config for rename
* fix minor typos

* [TASK] Use same convention homefolder for git setup like mentioned in other places

* [TASK] Move `attention` block to `EXT:styleguide` point

* [TASK] Use `git commit -a` instead of the not wildy known `git commit .`

---------

Co-authored-by: Stefan Frömken <[email protected]>
Co-authored-by: Stefan Bürk <[email protected]>

Author: 3 people

Documentation/BugfixingAZ/Index.rst

@@ -42,7 +42,8 @@ Step by Step Walkthrough
 ========================
 
 You should have a cloned Git repository with a working TYPO3 installation
-as described in :ref:`setup <setup>`. Especially the
+as described in :ref:`setup <setup>` (or via the
+:ref:`Quick start guide <quickstart>`). Especially the
 :ref:`Git setup <Setting-up-your-Git-environment>` is required.
 
 .. rst-class:: bignums-xxl
@@ -182,6 +183,7 @@ as described in :ref:`setup <setup>`. Especially the
 
 #. Optional: Advertise review on Slack channel
 
+.. _announce-slack:
    Once your push to Gerrit_ goes through, you will receive a URL for your new
    change. If you are on `Slack <https://typo3.slack.com>`__ you can now advertise
    your new change in the **#typo3-cms-coredev** channel. You can get a preformatted

Documentation/HandlingAPatch/CleanupTypo3.rst

@@ -16,12 +16,13 @@ Cleanup git repository
 
 Before :ref:`Cherry-picking a patch <cherry-pick-a-patch>` or starting a new patch:
 
-.. code-block:: bash
-   :caption: shell command
+..  code-block:: bash
+    :caption: **Reset local repository**
 
-   git fetch --all
-   git reset --hard origin/main
-   git pull --rebase
+    Build/Scripts/runTests.sh -s clean && \
+        git fetch --all && \
+        git reset --hard origin/main && \
+        git pull --rebase
 
 
 .. _cleanup-typo3:
@@ -35,31 +36,16 @@ cleanup your TYPO3 installation.
 It depends on the files that have changed, what you need to execute. In
 any case or if in doubt, you can safely perform all steps.
 
-**Flush the cache**:
+..  code-block:: bash
+    :caption: **Flush the cache**:
 
-.. code-block:: bash
-   :caption: shell command
+    ddev typo3 cache:flush && \
+        ddev typo3 cache:warmup
 
-   Build/Scripts/runTests.sh -s clean
-   # For DDEV environments, prefix with `ddev ...`
-   bin/typo3 cache:flush
-   bin/typo3 cache:warmup
+..  code-block:: bash
+    :caption: **Changes in composer.json**:
 
-**Changes in composer.json**:
-
-.. tabs::
-
-   .. group-tab:: runTests.sh
-
-      .. code-block:: bash
-
-         Build/Scripts/runTests.sh -s composerInstall
-
-   .. group-tab:: direct command
-
-      .. code-block:: bash
-
-         composer install
+    Build/Scripts/runTests.sh -s composerInstall
 
 **Changes in .css / .js files**:
 
@@ -69,14 +55,50 @@ Delete browser cache or
 
 Also you may need to create the JS/CSS assets:
 
-   .. code-block:: bash
+..  code-block:: bash
 
-      ./Build/Scripts/runTests.sh -s buildCss
-      ./Build/Scripts/runTests.sh -s buildJavascript
+    ./Build/Scripts/runTests.sh -s buildCss && \
+        ./Build/Scripts/runTests.sh -s buildJavascript
 
 **Changes in DB schema (ext_tables.sql)**:
 
+..  code:: bash
+    :caption: Create missing tables and fields
+
+    ddev typo3 extension:setup
+
 :guilabel:`Maintenance: Analyze Database Structure, Apply selected changes.`
 
 .. image:: /Images/ManualScreenshots/analyze.svg
    :class: with-shadow
+
+**Update core-testing docker images**
+
+..  code:: bash
+    :caption:  **Pull latest core-testing images versions**
+
+    ./Build/Scripts/runTests.sh -u
+
+One-liner command
+~~~~~~~~~~~~~~~~~
+
+If you want to reset your local installation in one go, you could use the following
+one-liner command, combining the mentioned parts from above:
+
+..  code:: bash
+    :caption: **Reset local repository to upstream state**
+
+    ./Build/Scripts/runTests.sh -u && \
+        Build/Scripts/runTests.sh -s clean && \
+        git fetch --all && \
+        git reset --hard origin/main && \
+        git pull --rebase && \
+        ./Build/Scripts/runTests.sh composerInstall && \
+        ddev typo3 cache:flush && \
+        ddev typo3 cache:warmup && \
+        ddev typo3 extension:setup
+
+..  note::
+
+    You may still check the `Database Analyzer` in the backend for changes or
+    removed columns and tables to ensure a clean state.

Documentation/Images/Quickstart/confirm-typo3.png

@@ -30,6 +30,10 @@ TYPO3 Contribution Guide - Core Development
 
 On these pages you will learn how to become a TYPO3 Core contributor.
 
+.. rst-class:: horizbuttons-primary-m
+
+*  :ref:`Quick Start: Contribute in under 30 Minutes! <quickstart>`
+
 ----
 
 **Table of Contents:**
@@ -63,6 +67,7 @@ On these pages you will learn how to become a TYPO3 Core contributor.
    :titlesonly:
    :caption: HOWTOS
 
+   Quickstart/Index
    ReportingAnIssue/Index
    BugfixingAZ/Index
    Build/Index

Documentation/Images/Quickstart/mail-confirm1.png

@@ -0,0 +1,74 @@
+:navigation-title: Prerequisites
+..  include:: /Includes.rst.txt
+
+..  index::
+    single: Prerequisites
+
+..  _quickstart-prerequisites:
+
+Quick Start: Prerequisites
+==========================
+
+We will not explain you how to set up the following prerequisites.
+There are several tutorials for this on the web, and if you follow
+the Quick Start guide, you should know how to do this.
+
+..  rst-class:: bignums-xxl
+
+1.  Operating System
+
+    A computer running Windows with WSL2, macOS or Linux - connected to
+    the Internet.
+
+2.  Docker
+
+    Either the "original" `Docker Desktop <https://www.docker.com/products/docker-desktop/>`__
+    or an alternative like `OrbStack <https://orbstack.dev/>`__, `Podman <https://podman.io/>`__,
+    `Colima <https://github.com/abiosoft/colima>`__ or others. Linux users
+    do not need to install any `Desktop` variants, but can use their base
+    Docker or Podman setup.
+
+3.  DDEV
+
+    `DDEV <https://ddev.com>`__ is a layer on top of Docker. How to utilize it is
+    covered in this guide.
+
+4.  Terminal (Bash)
+
+    Your operating system needs to provide a Bash terminal, many steps of this guide
+    will be executed on the shell.
+
+    You are free to use another local shell for your work, but the scripts
+    provided by the TYPO3 Core (most importantly `runTests.sh`) require Bash
+    to be available.
+
+5.  Git client
+
+    This guide expects you can execute `git` terminal commands.
+
+    This guide uses the *https* method to connect to GitHub, so you do not
+    need to have a GitHub account.
+
+6.  SSH client plus SSH key(s) and an email account
+
+    This guide expects you can execute `ssh` terminal commands and connect to
+    foreign hosts. You will need a private SSH key pair and know how to authenticate
+    with it. You need an email account to setup accounts.
+
+7.  PHP IDE / Editor
+
+    It is recommended to use a good PHP IDE. As part of the target audience of this guide
+    you should already use something like PhpStorm, Visual Studio Code, vi(m)...
+
+..  _quickstart-assumptions:
+8.  Assumed path structure and name usage
+
+    We will use:
+
+    * **$HOME/work/TYPO3-Contribute/** as your working directory (created in the guide).
+    * **John Doe** to be your name.
+    * **[email protected]** to be your email address that you used for all accounts.
+    * **john-doe** to be your TYPO3.org username.
+    * A TYPO3 **legacy mode** installation (Non-Composer) with MariaDB 10.11 and PHP 8.2.
+
+    Adjust any occurences of this to match your environment.

Documentation/Images/Quickstart/mail-confirm2.png

@@ -0,0 +1,44 @@
+:navigation-title: Accounts
+..  include:: /Includes.rst.txt
+
+..  index::
+    single: Accounts
+
+..  _quickstart-accounts:
+
+Quick Start: Accounts needed
+============================
+
+
+
+..  rst-class:: bignums-xxl
+
+1.  My TYPO3 (`https://my.typo3.org`__)
+
+    Vital account! Acts as a Single Sign On (SSO) provider for
+    several other services. See :ref:`TYPO3Account`.
+
+2.  Gerrit (`https://review.typo3.org`__)
+
+    The code review system that is used for your code contributions.
+    There, all patches are commented and voted/approved/rejected.
+
+    First login via the `My TYPO3` SSO account. Afterwards you need to upload
+    your SSH public key here. See :ref:`GerritAccount`.
+
+3.  Forge (`https://forge.typo3.org/`__)
+
+    The issue tracking platform (Redmine) where bugs and feature
+    requests are reported. Every patch in Gerrit needs to have
+    a corresponding issue.
+
+    You login here via the `My TYPO3` SSO account.
+
+4.  Slack (`https://typo3.slack.com/`__)
+
+    The chat platform where developers get in touch with each other.
+    The channel `#typo3-cms-coredev` is important.
+
+    You need to register an account for Slack, see `https://typo3.org/community/meet/chat-slack/`__
+    and :ref:`slack-account`.
+

Documentation/Images/Quickstart/register-typo3.png

@@ -0,0 +1,65 @@
+:navigation-title: Git
+..  include:: /Includes.rst.txt
+
+..  index::
+    single: Git repository
+
+..  _quickstart-git:
+
+Quick Start: Set up Git repository
+==================================
+
+..  tip::
+
+    You may want to adapt some commands that are shown here.
+    Copy them by using the copy icon in the code block, paste them
+    in a raw text file or editor, adjust the values. Then copy it
+    from there to paste it into your terminal again.
+
+..  rst-class:: bignums-xxl
+
+1.  Init directory and clone Repository
+
+    ..  code:: bash
+        :caption: **Create contribution folder and clone TYPO3 into a it**
+
+            mkdir -p $HOME/work/TYPO3-Contribute && \
+                cd $HOME/work/TYPO3-Contribute && \
+                git clone https://github.com/typo3/typo3.git .
+
+2.  Set up Git specifics
+
+    ..  note::
+
+        Remember that we use some convetions for username and email, see
+        :ref:`prerequisite assumptions <quickstart-assumptions>.
+
+    ..  code:: bash
+        :caption: **Set up git user meta data and repository**
+
+        git config user.name "John Doe" && \
+            git config user.email "[email protected]" && \
+            git config remote.origin.pushurl \
+                ssh://[email protected]:29418/Packages/TYPO3.CMS.git && \
+            git config remote.origin.push +refs/heads/main:refs/for/main
+
+    ..  code:: bash
+        :caption: **Configure recommended git options only for the repository**
+
+        git config branch.autosetuprebase remote
+
+    ..  code:: bash
+        :caption: **Install hooks and git commit template**
+
+        mkdir -p .git/hooks && \
+          cp Build/git-hooks/commit-msg .git/hooks/commit-msg && \
+          cp Build/git-hooks/unix+mac/pre-commit .git/hooks/ && \
+          chmod +x .git/hooks/commit-msg && \
+          chmod +x .git/hooks/pre-commit && \
+          {
+            echo '[BUGFIX|TASK|FEATURE|DOCS]'
+            echo ''
+            echo 'Resolves: #'
+            echo 'Releases: main'
+          } > $HOME/.gitmessage-typo3.txt && \
+          git config commit.template $HOME/.gitmessage-typo3.txt