Add page: Tips for new contributors

Related: TYPO3-Documentation#58

Documentation/Community/Index.rst

@@ -17,7 +17,7 @@ to ask others, if you can't find the information you need.
    single: Tools; Slack
    single: Slack
 
-.. _slack:
+.. _communitySlack:
 
 Slack
 =====

Documentation/HandlingAPatch/Index.rst

@@ -42,6 +42,7 @@ automatically run on every patch (set), the results being shown as a +1 or
 .. toctree::
    :titlesonly:
 
+   TipsForNewContributors
    GerritBasics
    FindAReview
    CherryPick
@@ -53,3 +54,4 @@ automatically run on every patch (set), the results being shown as a +1 or
    Backporting
    Revert
 
+

Documentation/HandlingAPatch/TipsForNewContributors.rst

@@ -0,0 +1,117 @@
+.. include:: ../Includes.txt
+
+
+.. index::
+   single: Gerrit
+   single: NewContributors
+
+.. _new-contributors-tips:
+
+=========================
+Tips for new contributors
+=========================
+
+You are a fresh contributor. You found an issue in the core you wanted to
+see fixed, you fought your way through the code to find a solution, you
+are satisfied with it, you :ref:`setup your environment <setup>`, you
+figured out how to :ref:`create a patch and push to Gerrit <_Fixing-a-bug-A-Z>`,
+you managed to :ref:`create a forge issue <bugreporting-index>` and you finally
+pushed your patch!
+
+Congratulations on your first patch! That is great!
+
+Now your patch is hanging around in the review queue on
+`Gerrit <https://review.typo3.org/>`__ and either nothing
+happens, it is voted down, people tell you your patch is not good enough
+or suggestions are made to improve it and you don't know how.
+
+Don't despair young padawan! The community around TYPO3 tries to act friendly
+and helpful, we're not hurting anyone on purpose. We're open to anyone and
+especially like to see new contributors and try to help getting them onboarded
+and up to speed. Please consider the following things before becoming
+frustrated or giving up:
+
+* Most of the time spend on TYPO3 CMS core development is free and not payed.
+  This gives contributors and reviewers freedom on what they work on.
+  Unfortunately, this also means that sometimes a patch is not given the
+  dedication it should receive.
+
+* The review queue is often longer than the review power available. Sometimes
+  patches are lost in the queue and are forgotten just because there is other
+  hot stuff being worked on.
+
+* Parts of the team usually work on something bigger. It may happen that some
+  patches in the hot areas are merged very quickly while others get stuck.
+  This is somehow natural since at any given time some reviewers usually
+  focus on certain areas to get them right, so there is no time for everything
+  else.
+
+* Sometimes the whole team focuses on different stuff. For example, usually
+  around "big" releases, the team focuses on bug fixing, so feature patches
+  may get stuck for some time.
+
+* Sometimes large parts of the active contributors are inactive at the same
+  time. There are for example main holiday sessions with low overall activity.
+
+* Sometimes getting little or no feedback on patches also has technical reasons.
+  Maybe the issue description is unfortunate or not understood, maybe there is
+  no documented way on how to reproduce a certain issue, or the bug or feature
+  is bogus, or the issue is so complex and hard to solve that no one really
+  wants to get hands dirty on it.
+
+What you can do to get feedback
+===============================
+
+Here are some things you can do to raise awareness and get more feedback on
+your patch and to help getting it merged:
+
+* Raise awareness: You are allowed to "ping" a patch once in a while. For
+  example, you could add a comment "Hey, what is the status here, how to
+  proceed with this patch?". This will raise the issue to TOP 1 in the
+  queue and increases your chance of feedback. In general: Ask what is
+  wrong, raise awareness, ask what is missing.
+
+* Ask for help: It may be helpful to get in closer contact to the active
+  contributors. Sometimes, issues can be solved in a better way if they are
+  coordinated in direct chat. The TYPO3 CMS team uses Slack as
+  instant communication platform. You are always welcome to join the
+  #typo3-cms-coredev channel and ask for direct help on your pending patches.
+  Please see :ref:`slack` for more information on how to join slack.
+  Joining the #typo3-cms-coredev Slack channel usually helps sorting out
+  things and gives a much better feeling on how the team works
+  and what is going on.
+
+How to improve your patch
+=========================
+
+It happens quite often that the first version of a patch
+is not merged directly and needs a couple of patch sets before it is
+finalized. In fact, merging "Patch Set 1" is the exception, and having
+something merged in less than an hour is rather seldom. We're trying to
+do things right, sometimes patches go through a whole lot of patch sets
+and evolve in Gerrit until everyone is satisfied. This can take some time.
+
+This is what you can do:
+
+* If reviewers make specific suggestions to improve your patch follow these
+  suggestions and :ref:`upload another patchset <lifeOfAPatch-improve-patch>`.
+
+* If you do not know what the suggestions mean or are unsure what to do, ask
+  for help on :ref:`Slack <slack>` #typo3-cms-coredev.
+
+* Act helpful and friendly: Chances are higher to get your stuff in if your
+  way of communication is fair. This is even more important for reviewers
+  and active contributors, we do not allow ranters and haters in our team
+  and we try to stick to our
+  `Code of conduct <https://typo3.org/community/code-of-conduct/>`__
+  Please keep that in mind when working with us. You will be rewarded with
+  the pleasure of working with a group of pretty smart people if you act
+  accordingly.
+
+* Don't get frustrated by -1 votes: Voting a patch down is a natural process
+  in the review system and is not a sign that we hate you, your patch or your
+  kitten. Our goal is to only merge things that are verified to be ready to
+  go. A -1 basically blocks a patch from merging for a reason, and reviewers
+  always add information on what is wrong or missing. Everyone wants to
+  improve the system, so a -1 is just one method to achieve this.
+