[TASK] Rework smaller parts to add specific notes (#339)

* [TASK] Rework smaller parts to add specific notes

(This may use some :ref: links which are committed seperately)

* Apply suggestions from code review

---------

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

Author: garvinhicking

Documentation/AddingDocumentation/Index.rst

@@ -198,9 +198,8 @@ in :ref:`h2document:render-documentation-with-docker`.
 
 .. important::
 
-   If you switch branches, you should rebuild everything. You can either remove the folder
-   :file:`Documentation-GENERATED-temp/Cache` and all its contents or run `dockrun_t3rd
-   makehtml-no-cache` which has the same effect.
+   If you switch branches, you should rebuild everything. You can simply remove the folder
+   :file:`Documentation-GENERATED-temp/Cache` and all its contents.
 
 .. _documentation-main:
 

Documentation/Appendix/HowToDeprecateThings.rst

@@ -18,6 +18,12 @@ or change functionality in the TYPO3 Core, it has to be deprecated first.
     Upon deprecating or removing functionality the change must be added
     to the :ref:`Extension scanner <extension-scanner>` whenever possible.
 
+..  note::
+    It's not always possible to "deprecate" everything. In some cases,
+    hard breaking changes must be introduced. These need to be addressed
+    and discussed with much care beyond the scope of this chapter, and can
+    only occur in new major versions of TYPO3 in the `X.0.x` focus release.
+
 Here is how:
 
 

Documentation/Appendix/OSX/InstallGrunt.rst

@@ -10,6 +10,11 @@
 GRUNT install on OSX
 ====================
 
+..  hint::
+
+   You may not need this at all, if you are using :ref:`runTests.sh <runtests_sh>`
+   with dockerized environment for building all assets.
+
 First off, make sure you installed **npm** like described :ref:`here<osx-npm>`.
 
 In your Terminal app navigate to the folder that you cloned the TYPO3 source into. Switch into the ``Build`` folder and run

Documentation/Appendix/OSX/InstallNpm.rst

@@ -10,6 +10,11 @@
 Npm install on OSX
 ===================
 
+..  hint::
+
+   You may not need this at all, if you are using :ref:`runTests.sh <runtests_sh>`
+   with dockerized environment for building all assets.
+
 Head over to https://docs.npmjs.com/cli/ and follow the install instructions.
 
 Once you have installed it, you can open up the Terminal app which is located under Applications/Utilities on your mac.

Documentation/Build/Index.rst

@@ -35,3 +35,6 @@ It is also possible to lint the files locally:
 
    Build/Scripts/runTests.sh -s lintScss
    Build/Scripts/runTests.sh -s lintTypescript
+
+Remember to commit the compiled files alongside any patches, they are part
+of the monorepo.

Documentation/CheatSheets/Git.rst

@@ -132,6 +132,8 @@ This assumes, you have correctly configured your remote as described in
 
 .. note::
    Pushing to `refs/publish` is deprecated, we now push to `refs/for`.
+   Check out :ref:`git-commit-with-message` on how to specify a distinct
+   small message alongsite your patch set.
 
 .. _git-work-in-progress:
 

Documentation/Community/Index.rst

@@ -45,8 +45,10 @@ any TYPO3 event in some way or another.
 * For an up-to-date list of events, see `Events on typo3.org
   <https://typo3.org/community/events/>`__
 
-Look for events like "Review Friday", "Code Sprints" and "Developer Days".
-Next, we will describe some events that are relevant for core
+Look for events like "Review Friday", "Code Sprints" and "Developer Days"
+or one of the many "BarCamps".
+
+Next, we will describe some events that are relevant for Core
 contribution. They are not specifically targeted at providing support,
 but the event may be open to new Core contributors and may give
 you the opportunity to ask questions and get help. In any case,

Documentation/ReportingAnIssue/Index.rst

@@ -24,6 +24,11 @@ Introduction to Forge
 
 The issue tracker Forge is currently based on Redmine. It is used to
 report and handle open issues (including bugs and feature requests).
+
+Note that Forge is not only used for the Community to report bugs
+and features, but also the Core development team creates issues for
+each and every change to TYPO3.
+
 First, get yourself an account, see
 :ref:`TYPO3-Guide-ContributionWorkflow-Account`.
 
@@ -49,6 +54,13 @@ something similar has already been reported.
 easy to find existing issues. Filters are located on the the left hand
 side of the navigation menu. You can use this feature to help refine searches.
 
+Of course you are also able to use the search functionality of
+`Forge <https://forge.typo3.org>`__ itself, which offers some more specific
+filter options.
+
+You help the people maintaining the issue tracker a lot by first making sure
+your problem is not covered already. The less duplicate issues our team needs
+to triage, the more time we have for actually addressing bugs and features.
 
 .. index::
    single: Issue Reporting Workflow; Identifying
@@ -66,7 +78,8 @@ Remove side effects
    Work on a TYPO3 instance which is as clean as possible so you can
    rule out extensions messing with the TYPO3 Core. If you need to set
    up an extension to illustrate the problem, make sure it is as free
-   of side effects as possible.
+   of side effects as possible. Ideally, try to reproduce your
+   problem or feature by using existing Core extensions (like :ref:`use-styleguide`).
 
 Narrow down the problem
    Try different browsers, this will help the team (and you) a lot to
@@ -134,7 +147,8 @@ be using the most are **Feature** and **Bug**.
 
 The others are mostly for internal organization (like **Stories** and **Epics**)
 and things which aren't really a feature or a bug... they are just **Tasks**
-somebody needs to take care of.
+somebody needs to take care of, because the Core development team also uses
+this system for their daily work.
 
 
 
@@ -153,7 +167,8 @@ a report for yourself :)
 .. tip::
 
    Remember, the subject is also helpful for people searching for already
-   existing issues. Be as clear and precise as possible!
+   existing issues. Be as clear and precise as possible! Also try to not mis-spell
+   vital keywords (for example use "extbase" and not "ext-bse").
 
 Bad example:
    Bug
@@ -298,7 +313,7 @@ It is important to provide **the specific information that is necessary** to be
 able to **understand**, **reproduce** and **fix** the bug.
 
 Use your common sense and your experience to guide you: What would you need if you
-wanted to find the bug in the code and fix it? What do you need if you want to
+wanted to find the bug in the code and fix it yourself? What do you need if you want to
 reproduce it to debug it or test if the patch solves the problem?
 
 A good bug report should contain all or any of these elements:
@@ -309,10 +324,10 @@ A good bug report should contain all or any of these elements:
 
    * A brief description of your environment. Depending on the nature of
      the bug it *might* include your operating system
-     (Windows, Linux, macOS, ...), the full version of TYPO3, the webserver
-     used, the database used (mySql, SQLServer, ...) and its version.
-     In any case, the full version of TYPO3 (e.g. 9.5.1) is very helpful. If
-     your bug is reproducible on several versions (e.g. 10.1.0 and 9.5.1),
+     (Windows, Linux, macOS, ...), the full version of TYPO3 and PHP, the webserver
+     used, the database used (MySQL, MariaDB, ...) and its version.
+     In any case, the full version of TYPO3 (e.g. 12.4.16) is very helpful. If
+     your bug is reproducible on several versions (e.g. 13.2.1 and 12.4.16),
      that is helpful as well.
    * A description of the TYPO3 setup that you are using or that is necessary
      to trigger the bug. Your issue came out using TYPO3 with multiple

Documentation/Setup/Git/Index.rst

@@ -66,6 +66,9 @@ Clone the TYPO3 CMS core repository:
 
            git clone https://github.com/typo3/typo3.git .
 
+Of course you can also use your custom user-specific workspace like
+:file:`/home/kaspar/TYPO3-Contribution/` to store the files, as you
+do not necessarily need to run a webserver to later setup your installation.
 
 
 .. index::
@@ -196,6 +199,8 @@ when you do `git push`:
 
    git config remote.origin.push +refs/heads/main:refs/for/main
 
+Reminder: The TYPO3 source repository is hosted on GitLab. That Git repository is only mirrored to the TYPO3 GitHub
+repository. Gerrit is coupled to GitLab.
 
 .. index::
    single: Code Contribution Workflow; Commit Message Template