From 5ac7d89e360528957e94fa23595b1a5b8ed52eb8 Mon Sep 17 00:00:00 2001 From: Stephanie Gawroriski Date: Sat, 21 Aug 2021 20:28:12 -0400 Subject: [PATCH 1/4] Part 1 rework of contributing. --- CONTRIBUTING.md | 43 ++++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f815b0994b..2e67f7e2ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,19 +1,36 @@ # 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. +## Submitting Bug Reports -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. +Bug reports in _RetroArch_ may fall into one of two categories: + + * _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. # Pull Requests Outside contributions are generally only accepted in the form of a pull request. The process is very simple. @@ -49,10 +66,6 @@ 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. -# IRC -Active development happens on [Discord](https://discordapp.com/invite/27Xxm2h). -We value discussing things in "real-time". - # 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. From 1855ce5fc7a03fb223c515db1cc28714056c8381 Mon Sep 17 00:00:00 2001 From: Stephanie Gawroriski Date: Sun, 22 Aug 2021 19:18:00 -0400 Subject: [PATCH 2/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++-------------------- 1 file changed, 45 insertions(+), 30 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2e67f7e2ac..6ab414df38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,40 +32,55 @@ If the issue occurs during runtime, please paste the verbose log output: 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. -# 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. +## Submitting Pull Requests -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. +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 -# 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. +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. + +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. From d44f3e1239f835ebd70cc0463f1b4fb7f647ada7 Mon Sep 17 00:00:00 2001 From: Stephanie Gawroriski Date: Sun, 22 Aug 2021 19:24:14 -0400 Subject: [PATCH 3/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ab414df38..3eb555de99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,11 @@ Active discussions happen on our [Discord](https://discordapp.com/invite/27Xxm2h the _Programming_ channel category. We value discussions that happen in real time around these contributions. +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. + ## Submitting Bug Reports Bug reports in _RetroArch_ may fall into one of two categories: From cd3e8182108cf7f5917055ad90b3042abb416de3 Mon Sep 17 00:00:00 2001 From: Stephanie Gawroriski Date: Wed, 25 Aug 2021 10:54:04 -0400 Subject: [PATCH 4/4] Add coding standards. --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3eb555de99..10bdf189fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,6 +70,8 @@ through the existing code to get a feel for the coding style. When submitting a 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. +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