mirror/RetroArch
1
0
Fork 0
mirror of https://github.com/libretro/RetroArch synced 2025-02-01 09:32:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #12874 from libretro/social-update

Browse Source 
Contributing guidelines update.
This commit is contained in:
Autechre 2021-08-25 21:16:48 +02:00 committed by GitHub
commit 5ca99fdb51
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 79 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
CONTRIBUTING.md
View File

@ -1,58 +1,93 @@
# Contributing to RetroArch # Contributing to RetroArch
If you are a developer and want to contribute to the development of RetroArch, please read this. If you are a developer who wishes to contribute to the development of _RetroArch_; or if you have
If you have found a bug and want to submit a minor patch or a bug report, please read this as well. found a bug and wish to submit a minor patch and/or bug report, please read this document.
# Submitting a bug report Active discussions happen on our [Discord](https://discordapp.com/invite/27Xxm2h), mostly within
When submitting a bug report, make sure that the bug is local to RetroArch. the _Programming_ channel category. We value discussions that happen in real time around
A bug in a libretro core or something deemed to be external is likely to be closed very fast. these contributions.
If you still suspect a bug in RetroArch, make sure to test with several cores to make sure.
If you have troubles building RetroArch on Linux/BSD/OSX, make sure to paste shell output of ./configure, Please do note that contributors to _RetroArch_ do such contributions within their spare time.
as well as config.log and shell output of make. If building on Windows, just paste shell output of make. 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. ## Submitting Bug Reports
If using Phoenix frontend, you can find log in (File -> Show Log) after running.
In console, make sure to run with verbose (-v) flag.
# Pull Requests Bug reports in _RetroArch_ may fall into one of two categories:
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.
If you want to develop a larger feature, * _RetroArch_ itself, the user interface and API around all of the various cores.
we'd like to discuss this first (ideally on IRC) so that you don't risk developing something * Individual _Core_, of which interact with _RetroArch_.
that won't be merged. A pull request with a proof-of-concept is fine, but please indicate so.
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 ## 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 If you wish to contribute additional functionality to _libretro_'s API, there are considerations
Having a consistent code style throughout the code base is highly valued. that must be accepted. Please note that because this API affects multiple different projects, we
Please look through the code to get a feel for the coding style. highly value and require API and ABI stability and backwards-compatibility. Due to this
A pull request may be asked to fix the coding style before submission. requirement, there will be additional scrutiny in reviews for this added functionality.
In other cases, a pull request may be followed up with a "style nit commit".
## Non-obvious things: Any and all features will be added only when **necessary** for an existing _libretro_ core to
- 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. properly function. Hypothetical implementations of _libretro_ are not considered.
- 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.
# Copyright Headers and AUTHORS ## Coding style
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.
# IRC We highly value a consistent code style throughout the entire code base, please make sure you look
Active development happens on [Discord](https://discordapp.com/invite/27Xxm2h). through the existing code to get a feel for the coding style. When submitting a pull request, it may
We value discussing things in "real-time". 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 For full guidelines please see the [Coding Standards](https://docs.libretro.com/development/coding-standards/).
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. 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.