====== Contributor Guidelines ====== This is a temporary import of https://github.com/derickr/php-community-health/blob/master/contributor-guidelines.rst to allow voting on this proposal. This vote is preliminary, and is only to gauge support for this text. Contributor Guidelines ====================== This is a collection of suggests on how to improve communication and collaboration. About two thirds of this is reworked from the ancient wisdoms as encoded in http://php.net/mailing-lists.php and http://git.php.net/?p=php-src.git;a=blob_plain;f=README.MAILINGLIST_RULES;hb=HEAD Constructive Collaboration Guidelines ------------------------------------- This section presents a loose collection of guidelines that focus on encouraging constructive feedback on language proposals (RFCs) and other email threads. RFCs are used to introduce new features into the language. In some cases, discussions could benefit from more focus on collaborative improvements to an RFC, instead of comments to the tune of "I don't like it". The RFC process is primarily designed to improve RFCs, and by extend, PHP, before they are put up to vote. Even though you might incline to vote no on an RFC, you can still actively act to make the RFC and feature better. PHP is developed through the efforts of a large number of people. Collaboration is a Good Thing™, and mailinglists lets us do this. Thus, following some basic rules with regards to mailinglist usage will: * Make everybody happier, especially those responsible for developing PHP itself. * Help in making sure we all use our time more efficiently. * Prevent you from making a fool of yourself in public. * Increase the general level of good will on planet Earth. Below are several suggestions on how to provide constructive criticism on RFC and other related discussions: * Respect other people working on the project. * Make sure you know what you are talking about. PHP is a very large project that strives to be very open. The flip side is that the core developers are faced with a lot of requests. Make sure that you have done your research before posting to the entire developer community. * Write clear and unambiguous prose. It is better to be descriptive than to be concise. * Write as much as is necessary, but as little as you can get away with. * Not everyone that will read your post is a native English speaker, try to use simple words where possible. * Debate the technical issues, and ideas behind them, but never attack the person holding them. People will disagree, so be it. * When you disagree with a certain proposal, try to think whether there are changes that can be made to the RFC that will enable you to support it. If you come up with such improvements, respectfully propose them to the RFC author to try and evolve the idea into a better one. Only resort towards arguing against the RFC if you think it's a bad idea and you can think of no ways to improve it. When disagreeing, provide substantial reason instead of just saying "no". Try to outline specific points you disagree with and suggest ways of improvement. And remember, you can suggest improvements to an RFC even if you would not vote to support the RFC. * RFCs with patches have a much greater chance of acceptance than just asking the PHP developers to implement a feature for you. For one it makes the discussion more concrete and it shows that the poster put thought and time into the request. If you can't implement an idea yourself, try to find somebody to implement your ideas *before* proposing a feature. And here are a few things you should avoid while discussing features and other technical content: * Try to avoid hyperbole to defend your arguments. * Do not post when you are angry. Any post can wait a few hours. Review your post after a good breather or a good nights sleep. From this follows: Don't send a "quick email", especially during a heated debate. * If you are posting to an existing thread, make sure that you know what previous posters have said. This is even more important the longer the thread is already. * Think before you send "reply". Consider how the other party is likely to feel about the content. Reflect how you would feel if the same text was directed at you. Emotions are important and difficult, especially when you have never met persons in real life. * If you notice that your posting ratio is much higher than that of other people, double check the above rules. Try to wait a bit longer before sending your replies to give other people more time to digest your answers and more importantly give you the opportunity to make sure that you aggregate your current position into a single mail instead of multiple ones. * Consider taking a step back from a very active thread now and then. Maybe talking to some friends and fellow developers will help in understanding the other opinions better. Go discuss it with your local user group. * Do not hijack threads, by bringing up entirely new topics. Please create an entirely new thread copying anything you wish to quote into the new thread. E-mail Etiquette ---------------- This is a set of guidelines to make sure that your emails can reach the largest group of people without annoying them regarding form and layout. Realise that people can not always use the same email client, and that there is long standing etiquette to improve communication. - Please configure your email client to use a real name. - Please keep message signature short. Don't add legal disclaimers. - Do not top post. Place your answer underneath anyone you wish to quote and remove any previous comment that is not relevant to your post. There is a great guide at https://www.netmeister.org/news/learn2quote.html - Use a valid email address. Every new poster's email address is checked for validity through confirmation. - Send plain ASCII messages, no HTML-formatted emails please. - Turn on word wrapping so your entire message doesn't show up on a single line. - Be sure to click Reply-All to reply to list. Clicking Reply will email the author of the message privately. - No attachments please, just post a URL if you want someone to look at something. All attachments that are not send as "text/plain" will be stripped by our mailinglist software. - Don't GPG/PGP sign your messages. If you want people to be able to send you encrypted email, stick your key-locator in your signature - Don't hijack other peoples' threads. To post on a new topic, start a new message, don't reply and just change the subject. - Check the archives before posting a suggestion or question, chances are it has already been asked and answered a few times. - When asking a question, don't just tell us, "it doesn't work". Tell us what you are trying to accomplish, a short code snippet showing how you tried to solve it, what you expected to get and what you got instead. * Yes, I agree with them. * Yes, they mostly make sense, but could use some tweaks (send mail to the list!) * No, they mostly don't make sense (send mail to the list!)