Merge pull request #12874 from libretro/social-update

Contributing guidelines update.

CONTRIBUTING.md

@@ -1,58 +1,93 @@
 # Contributing to RetroArch
 
-If you are a developer and want to contribute to the development of RetroArch, please read this.
-If you have found a bug and want to submit a minor patch or a bug report, please read this as well.
+If you are a developer who wishes to contribute to the development of _RetroArch_; or if you have
+found a bug and wish to submit a minor patch and/or bug report, please read this document.
 
-# Submitting a bug report
-When submitting a bug report, make sure that the bug is local to RetroArch.
-A bug in a libretro core or something deemed to be external is likely to be closed very fast.
-If you still suspect a bug in RetroArch, make sure to test with several cores to make sure.
+Active discussions happen on our [Discord](https://discordapp.com/invite/27Xxm2h), mostly within
+the _Programming_ channel category. We value discussions that happen in real time around
+these contributions.
 
-If you have troubles building RetroArch on Linux/BSD/OSX, make sure to paste shell output of ./configure,
-as well as config.log and shell output of make. If building on Windows, just paste shell output of make.
+Please do note that contributors to _RetroArch_ do such contributions within their spare time.
+We do prefer to keep a professional and non-aggressive atmosphere around the project, along
+with any disagreements to be settled professionally without insults, name calling, or otherwise.
+If there are any issues, we are willing to have discussions about it.
 
-If the issue occurs during runtime, make sure to paste RetroArch's verbose log.
-If using Phoenix frontend, you can find log in (File -> Show Log) after running.
-In console, make sure to run with verbose (-v) flag.
+## Submitting Bug Reports
 
-# Pull Requests
-Outside contributions are generally only accepted in the form of a pull request. The process is very simple.
-Fork RetroArch, make your changes, and issue a pull request on GitHub. This can all be done within the browser.
-The changes are reviewed, and might be merged in. If the pull request isn't acceptable at the time,
-note that it's possible to continue pushing up commits to your branch.
+Bug reports in _RetroArch_ may fall into one of two categories:
 
-If you want to develop a larger feature,
-we'd like to discuss this first (ideally on IRC) so that you don't risk developing something
-that won't be merged. A pull request with a proof-of-concept is fine, but please indicate so.
+ * _RetroArch_ itself, the user interface and API around all of the various cores.
+ * Individual _Core_, of which interact with _RetroArch_.
+
+When submitting a bug report, ensure that the report is submitted to the correct repository.
+For _RetroArch_ itself, it is done by reporting a bug within the
+[RetroArch](https://github.com/libretro/RetroArch) repository. For other cores, please use
+the search function within the [libretro Organization](https://github.com/libretro) on
+GitHub. Issues that are specific to a core and not _RetroArch_ are likely to be closed very
+quickly. If an issue is suspected with _RetroArch_, please make sure to test with multiple
+cores to be sure that is is not isolated.
+
+If the issue occurs during runtime, please paste the verbose log output:
+
+ * If using the _Pheonix_ interface, the log will be in _File_ -> _Show Log_.
+ * If using the main interface, enable verbose logging with _Settings_ -> _Logging_ ->
+   _Logging Verbosity_. Ensure both _Log to File_ and _Timestamp log Files_ is enabled.
+ * Otherwise, run _RetroArch_ with the verbose (`-v`) flag.
+
+If the error happens during compilation and/or building, paste the output of `./configure`
+and `make` accordingly. If using an IDE, please paste any of the errors and log output.
+
+## Submitting Pull Requests
+
+Any and all contributions should be submitted through Pull Requests on
+[GitHub](https://github.com/libretro/RetroArch/pulls). The process requires that you fork the
+repository, make the appropriate changes, and then open a pull request on _GitHub_. If your
+pull request is for a proof-of-concept then please indicate as such.
+
+Your pull request will then be reviewed. There may be comments and requests for additional
+changes to be made. It may also be possible that the changes will not be accepted. Otherwise, it
+may be merged in when it is fully approved. The final approval of merge requests is at the
+discretion of the project.
+
+If you want to develop a larger feature or make broad changes, please do join our
+[Discord](https://discordapp.com/invite/27Xxm2h) server to discuss. The discussion is
+necessary to prevent the possibility of major work being done which will not be accepted at all.
 
 ## libretro API
-If you wish to add functionality to libretro's API, it can take some time to merge in, because changes
-to libretro API will affect other projects as well, and we highly value API/ABI stability.
-Features will only be added when deemed *necessary* for a concrete libretro core to function properly.
-Features will not be added on basis of hypothetical libretro implementations.
 
-# Coding style
-Having a consistent code style throughout the code base is highly valued.
-Please look through the code to get a feel for the coding style.
-A pull request may be asked to fix the coding style before submission.
-In other cases, a pull request may be followed up with a "style nit commit".
+If you wish to contribute additional functionality to _libretro_'s API, there are considerations
+that must be accepted. Please note that because this API affects multiple different projects, we
+highly value and require API and ABI stability and backwards-compatibility. Due to this
+requirement, there will be additional scrutiny in reviews for this added functionality.
 
-## Non-obvious things:
-  - Code should be both C89 and ISO C++ compatible. This dual requirement is for XBox360 and MSVC in general. Think of it as a C++ compatible subset of C99.
-  - Warnings are not allowed (-Wall). Make sure your code is warning-free. Note that warning sensitivity differs a bit across compiler versions.
-  - Using deprecated APIs is discouraged.
+Any and all features will be added only when **necessary** for an existing _libretro_ core to
+properly function. Hypothetical implementations of _libretro_ are not considered.
 
-# Copyright Headers and AUTHORS
-If you have contributed to a part of a source file (a chunk of code that's written by you),
-you should add yourself to the copyright header in that file.
-If you have contributed significantly
-(a feature, a contribution you can "name", e.g. "Added audio driver foo"), you should add yourself to AUTHORS file.
-We'd like your full name and email, and which features you have been part of.
+## Coding style
 
-# IRC
-Active development happens on [Discord](https://discordapp.com/invite/27Xxm2h).
-We value discussing things in "real-time".
+We highly value a consistent code style throughout the entire code base, please make sure you look
+through the existing code to get a feel for the coding style. When submitting a pull request, it may
+be asked to fix any coding style issues before submission. In other cases, there may be a follow-up
+pull request making the code style consistent.
 
-# Commit Access
-Contributors who show a track record of making good pull requests over time will eventually get commit access to the repo.
-This typically happens when the "overhead" of looking through pull requests over time becomes a burden.
+For full guidelines please see the [Coding Standards](https://docs.libretro.com/development/coding-standards/).
+
+Some non-obvious things to be aware of:
+
+  - Code should be both C89 and ISO C++ compatible. This is a requirement for XBox 360 and MSVC to
+    properly build. Think of it as a C++ compatible subset of C99.
+  - There must be no warnings in your code (enabled by `-Wall` for GCC compilers), do also note that
+    different compilers may produce different warnings.
+  - Avoid using deprecated APIs, these will be removed in the future at some point.
+
+## Copyright Headers and AUTHORS
+
+If you have contributed a chunk of source code that is written to you, you should add yourself to
+the copyright header in the file. If you have made a significant contribution you should add
+yourself to the `AUTHORS` file, adding your full name, e-mail, and the feature you worked on.
+
+## Commit Access
+
+Contributors who show a good track record of pull requests over time may eventually
+get commit access to the repository. This may happen when looking through pull requests
+over long amounts of time becomes a burden.