diff options
author | 2022-12-22 07:17:55 +1100 | |
---|---|---|
committer | 2022-12-22 07:17:55 +1100 | |
commit | e85a2899c597b290aa726cbdc4589818cb95565c (patch) | |
tree | 183c7e8898422107b6f33b17afacca194eda8b74 /docs/source/contributing/index.rst | |
parent | 0619912fb0b647934f025aff1beeccab2b67ae02 (diff) |
docs: Added preliminary guide for would-be contributors. (#10717) [Ryan Holtz, Vas Crabb, O. Galibert]
Diffstat (limited to 'docs/source/contributing/index.rst')
-rw-r--r-- | docs/source/contributing/index.rst | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst new file mode 100644 index 00000000000..df18b248374 --- /dev/null +++ b/docs/source/contributing/index.rst @@ -0,0 +1,144 @@ +.. _contributing: + +Contributing to MAME +==================== + +So you want to contribute to MAME but aren’t sure where to start? Well +the great news is that there’s always plenty to do for people with a +variety of skill sets. + + +.. _contributing-testing: + +Testing and reporting bugs +-------------------------- + +One thing MAME can always do with is more testing and bug reports. If +you’re familiar with a system that MAME emulates and notice something +wrong, or if you find a bug in MAME’s user interface, you can head over +to `MAME Testers <https://mametesters.org/>`_ and, assuming it isn’t +already reported, register an account and open an issue. Be sure to +read the `FAQ <https://mametesters.org/faq.html>`_ and +`rules <https://mametesters.org/rules.html>`_ first to ensure you start +out on the right foot. Please note that MAME Testers only accepts +user-facing bugs in tagged release versions. + +For other kinds of issues, we have +`GitHub Issues <https://github.com/mamedev/mame/issues/>`_. There’s a +bit more leeway here. For example we accept developer-facing issues +(e.g. bugs in internal APIs, or build system inadequacies), feature +requests, and major regressions before they make it into a released +version. Please respect the fact that the issue tracker is *not* a +discussion or support forum, it’s only for reporting reproducible +issues. Don’t open issues to ask questions or request support. Also, +keep in mind that the ``master`` branch is unstable. If the current +revision doesn’t compile at all or is completely broken, we’re probably +already aware of it and don’t need issues opened for that. Wait a while +and see if there’s an update. You might want to comment on the commit +in question with the compiler error message, particularly if you’re +compiling in an unorthodox but supported configuration. + +When opening an issue, remember to provide as much information as +possible to help others understand, reproduce, and diagnose the issue. +Things that are helpful to include: + +* The incorrect behaviour, and expected or correct behaviour. Be + specific: just saying it “doesn’t work” usually isn’t enough detail. +* Environment details, including your operating system, CPU + architecture, system locale, and display language, if applicable. For + video output bugs, note your video hardware (GPU), driver version, and + the MAME video output module you’re using. For input handling bugs, + include the input peripherals and MAME input modules you’re using. +* The exact version of MAME you’re using, including a git commit digest + if it isn’t a tagged release version, and any non-standard build + options. +* The exact system and software being emulated (may not be applicable + for issues with parts of MAME’s UI, like the system selection menu). + Include things like the selected BIOS version, and emulated peripheral + (slot device) configuration. +* Steps to reproduce the issue. Assume the person reading is familiar + with MAME itself, but not necessarily familiar with the emulated + system and software in question. For emulation issues, input + recordings and/or saved state files for reproducing the issue can be + invaluable. +* An original reference for the correct behaviour. If you have access + to the original hardware for the emulated system, it helps to make a + recording of the correct behaviour for comparison. + + +.. _contributing-code: + +Contributing to MAME’s source code +---------------------------------- + +MAME itself is written in C++, but that isn’t the sum total of the +source code. The source code also includes: + +* The documentation hosted on this site (and also included in releases + as a PDF), written in + `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ + markup. +* The supplied :ref:`plugins <plugins>`, written in + `Lua 5.3 <https://www.lua.org/manual/5.3/>`_. +* Internal layouts for emulated machines that need to display more than + a simple video screen. These are an XML application + :ref:`described here <layfile>`. +* The software lists, describing known software media for systems that + MAME emulates. MAME software lists are an XML application. +* The user interface translations, in GNU gettext PO format. They can + be edited with a good text editor, or a dedicated tool like + `Poedit <https://poedit.net/>`_. + +Our primary source code repository is +`hosted on GitHub <https://github.com/mamedev/mame/>`_. We prefer to +receive source code contributions in the form of +`pull requests <https://github.com/mamedev/mame/pulls>`_. You’ll need +to learn the basics of git distributed version control and familiarise +yourself with the git tools. The basic process for creating a pull +request is as follows: + +* Sign up for an account on GitHub. +* Create a fork of the mamedev/mame repository. +* Create a new branch off the ``master`` branch in your forked + repository. +* Clone your forked repository, and check out your new branch. +* Make your changes, and build and test them locally. +* Commit your changes, and push your branch to GitHub. +* Optionally enable GitHub Actions for your forked repository, allowing + your changes to be built on Windows, macOS and Linux. +* Open a pull request to merge your changes into the ``master`` branch + in the mamedev/mame repository. + +Please keep the following in mind (note that not all points are relevant +to all kinds of changes): + +* Make your commit messages descriptive. Please include what the change + affects, and what it’s supposed to achieve. A person reading the + commit log shouldn’t need to resort to examining the diff to get a + basic idea of what a commit is supposed to do. The default commit + messages provided by GitHub are completely useless, as they don’t give + any indication of what a change is supposed to do. +* Test your changes. Ensure that a full build of MAME completes, and + that the code you changed works. It’s a good idea to build with + ``DEBUG=1`` to check that assertions compile and don’t trigger. +* Use an enlightening pull request title and description. The title + should give a one-line summary of what the overall change affects and + what it’s supposed to do. The description should contain more detail. + Don’t leave the description empty and describe the change in comments, + as this makes searching and filtering more difficult. +* Be aware that GitHub Actions has opaque resource limits. It isn’t + clear when you’re close to the limits, and we’ve had contributors + banned from GitHub Actions for violating the limits. Even if you + appeal the ban, they still won’t tell you what the actual limits are, + justifying this by saying that if you know the limits, you can take + steps to evade them. If you enable GitHub Actions, consider not + pushing individual commits if you don’t need them to be automatically + built, or cancelling workflow runs when you don’t need the results. + +We have guidelines for specific parts of the source: + +.. toctree:: + :titlesonly: + + cxx + softlist |