[Contributing] Giving constructive criticism

Author: sstok

contributing/giving-constructive-criticism.rst

@@ -0,0 +1,154 @@
+Giving constructive criticism
+=============================
+
+:doc:`Reviewing issues and pull request </contributing/community/reviews>` is a great way to get started with
+contributing to the Symfony community. Anyone can do it! But before
+you give a comment, take a step back and think, is what you are about
+to say actually what you indent?
+
+Communicating over the internet with nothing but text can pose a
+big challenge, especially if you remember the Symfony community
+is world-wide and is composed of a wide variety of people with differing
+idea's and opinions.
+
+Not everyone speaks English, is able to use a keyboard, and some might
+even have dyslexia. And not to mention that some might have a
+bad experience from previous contributions (to other projects).
+
+Your not alone in this, this guide will try help you write
+constructive, respectful and helpful reviews and replies.
+
+.. tip::
+
+    This guide is not about lecturing you to "conform" or give-up
+    your ideas and opinions. But helping you to better communicate,
+    prevent possible confusion, and keeping the Symfony community a
+    welcoming place for everyone. **You are free to disagree with
+    someone's opinions just don't be disrespectful.**
+
+First of, accept that many programming decisions are opinions.
+Discuss trade offs, which you prefer, and reach a resolution quickly.
+It's not about being right or wrong, but using what works.
+
+Tone of voice
+-------------
+
+We don't expect you to be completely formal, or to even write error-free
+English. Just remember one thing: Don't swear, and be respectful to others
+
+Don't reply in anger or with an aggressive tone. You're angry, we understand
+that, but swearing/cursing and name calling doesn't really encourage anyone to
+help you. Take a deep breath, count to 10 and try to *clearly* explain what problems
+you encounter.
+
+Gender pronouns
+---------------
+
+While not "formally" required it's better to use gender-neutral pronouns.
+Unless someone "indicated" there pronouns, use "they", "them" instead of
+"he", "she", "his", "hers", "his/hers", "he/she", etc.
+
+And instead of saying "guys" it's better to use "folks", or Symfonions
+if you like that.
+
+Giving positive feedback
+------------------------
+
+While reviewing issues and pull request you may run into some suggestions
+(including patches) that don't reflect your idea's, are not good, or down
+right wrong.
+
+Now, instead of writing a lengthy comment why you think they are wrong.
+Consider the amount of work and time the author has spend on there idea.
+And how your response would make them feel;
+
+* Are you making a point only because you believe they are wrong?
+
+* Did you correctly understand there intention? or are you making assumptions?
+
+Maybe you can ask for clarification?, suggest an alternative? or
+provide a simple explanation *why* disagree with there proposal.
+
+Even if something *is* really wrong or "a bad idea", stay respectful and
+don't get into endless you-are-wrong discussions or "flame wars".
+
+* Good questions avoid judgment and avoid assumptions about the author's
+  perspective.
+
+* Avoid using terms that could be seen as referring to personal traits. ("dumb",
+  "stupid"). Assume everyone is intelligent and well-meaning.
+
+* Be explicit. Remember people don't always understand your intentions online.
+
+* Don't use hyperbole. ("always", "never", "endlessly", "nothing", "worst",
+  "horrible", "terrible").
+
+Instead of saying "This is a horrible idea" use something like
+"This can introduce issues in the future. Please make sure this is safe to use."
+
+Asking for changes
+------------------
+
+Rarely something is perfect from the start, while the code itself is good.
+It may not be optimal or conform the Symfony coding style.
+
+Again, understand the author already spend time on the issue and asking
+for (small) changes may be misinterpreted or seen as a personal attack.
+
+Be thankful for there work (so far), stay positive and really help them
+to make the contribution a great one. *Especially if they are a first
+time contributor.*
+
+Use words like "Please", "Thank you" and "Could you" instead of making demands;
+
+* "Thank you for your work so far. I left some suggestions for improvement
+  to make the code more readable."
+
+* "Your code contains some coding-style problems, can you fix these before
+  we merge? Thank you"
+
+* "Please use 4 spaces instead of tabs", "This needs be on the previous line";
+
+  During a pull request review you can usually leave more then one comment,
+  you don't have to use "Please" all the time. But it wouldn't hurt.
+
+It may not seem like much, but saying "Thank you" does make others feel
+more welcome.
+
+Making jokes (using humor)
+--------------------------
+
+In short: Don't be a troll; This violates the Code of Conduct and may
+even get you banned!
+
+OK, lets be honest. We all make jokes, some are funny and some are not.
+They don't put anyone of, right? Well, who's to tell. What's funny to one
+is offensive to another.
+
+In short. Keep it real. There is nothing wrong with using a meme or emoji
+from time to time, but don't over do it. And even then, keep it friendly.
+
+**Don't use sarcasm for a serious topic, that's not something that belongs
+to the Symfony community.** And don't marginalize someone's problems;
+"Well I guess that's not suppose to happen? 😆 ".
+
+Even if someone's explanation is "inviting to joke about", it's a real
+problem to them. Making jokes about this doesn't help with solving
+there problem and only makes them *feel stupid*. Instead try to discover
+what the problem is really about.
+
+If emoji, animated gifs, or humor aren't you, don't force them.
+
+Final words
+-----------
+
+Don't feel bad if you "failed" to follow these tips. As long as your
+intentions were good and you didn't really offended or insulted anyone;
+you can explain you misunderstood, you didn't meant to marginalize or
+simply failed.
+
+But don't say it "just because", if your apology is not really meant
+you *will* loose credibility and respect from other developers.
+
+*Don't do unto others what you don't want others to do unto you.*
+