From fe9e19d8ccf1823a0891d2df198292e0b0d53132 Mon Sep 17 00:00:00 2001
From: MutantAura <44103205+MutantAura@users.noreply.github.com>
Date: Fri, 22 Sep 2023 15:21:11 +0100
Subject: [PATCH] [INFRA] Addition of basic contributor guides and docs
 framework. (#5581)

* Addition of basic contributor docs.

- Main contributor guide landing page.
- C# codestyle doc.
- Pull request guide doc.

All files and structure heavily inspired by the dotnet/runtime docs: https://github.com/dotnet/runtime/tree/main/docs

* fix typos and review changes

* Update XML doc requirement & conversation review.
---
 CONTRIBUTING.md                        | 147 +++++++++++++++++++++++++
 docs/README.md                         |  40 +++++++
 docs/coding-guidelines/coding-style.md | 116 +++++++++++++++++++
 docs/workflow/pr-guide.md              |  56 ++++++++++
 4 files changed, 359 insertions(+)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 docs/README.md
 create mode 100644 docs/coding-guidelines/coding-style.md
 create mode 100644 docs/workflow/pr-guide.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..366eb84352
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,147 @@
+# Contribution to Ryujinx
+
+You can contribute to Ryujinx with PRs, testing of PRs and issues. Contributing code and other implementations is greatly appreciated alongside simply filing issues for problems you encounter.
+Please read the entire document before continuing as it can potentially save everyone involved a significant amount of time.
+
+# Quick Links
+
+* [Code Style Documentation](docs/coding-guidelines/coding-style.md)
+* [Pull Request Guidelines](docs/workflow/pr-guide.md)
+
+## Reporting Issues
+
+We always welcome bug reports, feature proposals and overall feedback. Here are a few tips on how you can make reporting your issue as effective as possible.
+
+### Identify Where to Report
+
+The Ryujinx codebase is distributed across multiple repositories in the [Ryujinx organization](https://github.com/Ryujinx). Depending on the feedback you might want to file the issue on a different repo. Here are a few common repos:
+
+* [Ryujinx/Ryujinx](https://github.com/Ryujinx/Ryujinx) Ryujinx core project files.
+* [Ryujinx/Ryujinx-Games-List](https://github.com/Ryujinx/Ryujinx-Games-List) Ryujinx game compatibility list.
+* [Ryujinx/Ryujinx-Website](https://github.com/Ryujinx/Ryujinx-Website) Ryujinx website source code.
+* [Ryujinx/Ryujinx-Ldn-Website](https://github.com/Ryujinx/Ryujinx-Ldn-Website) Ryujinx LDN website source code.
+
+### Finding Existing Issues
+
+Before filing a new issue, please search our [open issues](https://github.com/Ryujinx/Ryujinx/issues) to check if it already exists.
+
+If you do find an existing issue, please include your own feedback in the discussion. Do consider upvoting (👍 reaction) the original post, as this helps us prioritize popular issues in our backlog.
+
+### Writing a Good Feature Request
+
+Please review any feature requests already opened to both check it has not already been suggested, and to familiarize yourself with the format. When ready to submit a proposal, please use the [Feature Request issue template](https://github.com/Ryujinx/Ryujinx/issues/new?assignees=&labels=&projects=&template=feature_request.yml&title=%5BFeature+Request%5D).
+
+### Writing a Good Bug Report
+
+Good bug reports make it easier for maintainers to verify and root cause the underlying problem. The better a bug report, the faster the problem will be resolved. 
+Ideally, a bug report should contain the following information:
+
+* A high-level description of the problem.
+* A _minimal reproduction_, i.e. the smallest time commitment/configuration required to reproduce the wrong behavior. This can be in the form of a small homebrew application, or by providing a save file and reproduction steps for a specific game.
+* A description of the _expected behavior_, contrasted with the _actual behavior_ observed.
+* Information on the environment: OS/distro, CPU, GPU (including driver), RAM etc.
+* A Ryujinx log file of the run instance where the issue occurred. Log files can be found in `[Executable Folder]/Logs` and are named chronologically.
+* Additional information, e.g. is it a regression from previous versions? Are there any known workarounds?
+
+When ready to submit a bug report, please use the [Bug Report issue template](https://github.com/Ryujinx/Ryujinx/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D).
+
+## Contributing Changes
+
+Project maintainers will merge changes that both improve the project and meet our standards for code quality.
+
+The [Pull Request Guide](docs/workflow/pr-guide.md) and [License](https://github.com/Ryujinx/Ryujinx/blob/master/LICENSE.txt) docs define additional guidance.
+
+### DOs and DON'Ts
+
+Please do:
+
+* **DO** follow our [coding style](docs/coding-guidelines/coding-style.md) (C# code-specific).
+* **DO** give priority to the current style of the project or file you're changing even if it diverges from the general guidelines.
+* **DO** keep the discussions focused. When a new or related topic comes up
+  it's often better to create new issue than to side track the discussion.
+* **DO** clearly state on an issue that you are going to take on implementing it.
+* **DO** blog and tweet (or whatever) about your contributions, frequently!
+
+Please do not:
+
+* **DON'T** make PRs for style changes.
+* **DON'T** surprise us with big pull requests. Instead, file an issue and talk with us on Discord to start
+  a discussion so we can agree on a direction before you invest a large amount
+  of time.
+* **DON'T** commit code that you didn't write. If you find code that you think is a good fit to add to Ryujinx, file an issue or talk to us on Discord to start a discussion before proceeding.
+* **DON'T** submit PRs that alter licensing related files or headers. If you believe there's a problem with them, file an issue and we'll be happy to discuss it.
+
+### Suggested Workflow
+
+We use and recommend the following workflow:
+
+1. Create or find an issue for your work.
+    - You can skip this step for trivial changes.
+    - Get agreement from the team and the community that your proposed change is a good one if it is of significant size or changes core functionality.
+    - Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
+2. Create a personal fork of the repository on GitHub (if you don't already have one).
+3. In your fork, create a branch off of main (`git checkout -b mybranch`).
+    - Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
+4. Make and commit your changes to your branch.
+    - [Build Instructions](https://github.com/Ryujinx/Ryujinx#building) explains how to build and test.
+    - Commit messages should be clear statements of action and intent.
+6. Build the repository with your changes.
+    - Make sure that the builds are clean.
+    - Make sure that `dotnet format` has been run and any corrections tested and committed.
+7. Create a pull request (PR) against the Ryujinx/Ryujinx repository's **main** branch.
+    - State in the description what issue or improvement your change is addressing.
+    - Check if all the Continuous Integration checks are passing. Refer to [Actions](https://github.com/Ryujinx/Ryujinx/actions) to check for outstanding errors.
+8. Wait for feedback or approval of your changes from the [core development team](https://github.com/orgs/Ryujinx/teams/developers)
+    - Details about the pull request [review procedure](docs/workflow/ci/pr-guide.md).
+9. When the team members have signed off, and all checks are green, your PR will be merged.
+    - The next official build will automatically include your change.
+    - You can delete the branch you used for making the change.
+
+### Good First Issues
+
+The team marks the most straightforward issues as [good first issues](https://github.com/Ryujinx/Ryujinx/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). This set of issues is the place to start if you are interested in contributing but new to the codebase.
+
+### Commit Messages
+
+Please format commit messages as follows (based on [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)):
+
+```
+Summarize change in 50 characters or less
+
+Provide more detail after the first line. Leave one blank line below the
+summary and wrap all lines at 72 characters or less.
+
+If the change fixes an issue, leave another blank line after the final
+paragraph and indicate which issue is fixed in the specific format
+below.
+
+Fix #42
+```
+
+Also do your best to factor commits appropriately, not too large with unrelated things in the same commit, and not too small with the same small change applied N times in N different commits.
+
+### PR - CI Process
+
+The [Ryujinx continuous integration](https://github.com/Ryujinx/Ryujinx/actions) (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean or have bugs properly filed against flaky/unexpected failures that are unrelated to your change.
+
+If the CI build fails for any reason, the PR actions tab should be consulted for further information on the failure. There are a few usual suspects for such a failure:
+* `dotnet format` has not been run on the PR and has outstanding stylistic issues.
+* There is an error within the PR that fails a test or errors the compiler.
+* Random failure of the workflow can occasionally result in a CI failure. In this scenario a maintainer will manually restart the job.
+
+### PR Feedback
+
+Ryujinx team and community members will provide feedback on your change. Community feedback is highly valued. You may see the absence of team feedback if the community has already provided good review feedback.
+
+Two Ryujinx team members must review and approve every PR prior to merge. They will often reply with "LGTM, see nit". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".
+
+There are lots of thoughts and [approaches](https://github.com/antlr/antlr4-cpp/blob/master/CONTRIBUTING.md#emoji) for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.
+
+#### Copying Changes from Other Projects
+
+Ryujinx uses some implementations and frameworks from other projects. The following rules must be followed for PRs that include changes from another project:
+
+- The license of the file is [permissive](https://en.wikipedia.org/wiki/Permissive_free_software_licence).
+- The license of the file is left in-tact.
+- The contribution is correctly attributed in the [3rd party notices](https://github.com/Ryujinx/Ryujinx/blob/master/distribution/legal/THIRDPARTY.md) file in the repository, as needed.
+
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000..2213086f67
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,40 @@
+# Documents Index
+
+This repo includes several documents that explain both high-level and low-level concepts about Ryujinx and its functions. These are very useful for contributors, to get context that can be very difficult to acquire from just reading code.
+
+Intro to Ryujinx
+==================
+
+Ryujinx is an open-source Nintendo Switch emulator, created by gdkchan, written in C#. 
+* The CPU emulator, ARMeilleure, emulates an ARMv8 CPU and currently has support for most 64-bit ARMv8 and some of the ARMv7 (and older) instructions.
+* The GPU emulator emulates the Switch's Maxwell GPU using either the OpenGL (version 4.5 minimum), Vulkan, or Metal (via MoltenVK) APIs through a custom build of OpenTK or Silk.NET respectively.
+* Audio output is entirely supported via C# wrappers for SDL2, with OpenAL & libsoundio as fallbacks.
+
+Getting Started
+===============
+
+- [Installing the .NET SDK](https://dotnet.microsoft.com/download)
+- [Official .NET Docs](https://docs.microsoft.com/dotnet/core/)
+
+Contributing (Building, testing, benchmarking, profiling, etc.)
+===============
+
+If you want to contribute a code change to this repo, start here.
+
+- [Contributor Guide](../CONTRIBUTING.md)
+
+Coding Guidelines
+=================
+
+- [C# coding style](coding-guidelines/coding-style.md)
+- [Service Implementation Guidelines - WIP](https://gist.github.com/gdkchan/84ba88cd50efbe58d1babfaa7cd7c455)
+
+Project Docs
+=================
+
+To be added. Many project files will contain basic XML docs for key functions and classes in the meantime.
+
+Other Information
+=================
+
+- N/A
diff --git a/docs/coding-guidelines/coding-style.md b/docs/coding-guidelines/coding-style.md
new file mode 100644
index 0000000000..9c84055d61
--- /dev/null
+++ b/docs/coding-guidelines/coding-style.md
@@ -0,0 +1,116 @@
+# C# Coding Style
+
+The general rule we follow is "use Visual Studio defaults". 
+Using an IDE that supports the `.editorconfig` standard will make this much simpler.
+
+1. We use [Allman style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be properly indented on its own line and must not be nested in other statement blocks that use braces (See rule 18 for more details). One exception is that a `using` statement is permitted to be nested within another `using` statement by starting on the following line at the same indentation level, even if the nested `using` contains a controlled block.
+2. We use four spaces of indentation (no tabs).
+3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix internal and private instance fields with `_`, static fields with `s_` and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (e.g. `static readonly` not `readonly static`).  Public fields should be used sparingly and should use PascalCasing with no prefix when used.
+4. We avoid `this.` unless absolutely necessary.
+5. We always specify the visibility, even if it's the default (e.g.
+   `private string _foo` not `string _foo`). Visibility should be the first modifier (e.g.
+   `public abstract` not `abstract public`).
+6. Namespace imports should be specified at the top of the file, *outside* of `namespace` declarations.
+7. Avoid more than one empty line at any time. For example, do not have two
+   blank lines between members of a type.
+8. Avoid spurious free spaces.
+   For example avoid `if (someVar == 0)...`, where the dots mark the spurious free spaces.
+   Consider enabling "View White Space (Ctrl+R, Ctrl+W)" or "Edit -> Advanced -> View White Space" if using Visual Studio to aid detection.
+9. If a file happens to differ in style from these guidelines (e.g. private members are named `m_member`
+   rather than `_member`), the existing style in that file takes precedence.
+10. We only use `var` when the type is explicitly named on the right-hand side, typically due to either `new` or an explicit cast, e.g. `var stream = new FileStream(...)` not `var stream = OpenStandardInput()`.
+    - Similarly, target-typed `new()` can only be used when the type is explicitly named on the left-hand side, in a variable definition statement or a field definition statement. e.g. `FileStream stream = new(...);`, but not `stream = new(...);` (where the type was specified on a previous line).
+11. We use language keywords instead of BCL types (e.g. `int, string, float` instead of `Int32, String, Single`, etc) for both type references as well as method calls (e.g. `int.Parse` instead of `Int32.Parse`). See issue [#13976](https://github.com/dotnet/runtime/issues/13976) for examples.
+12. We use PascalCasing to name all our constant local variables and fields. The only exception is for interop code where the constant value should exactly match the name and value of the code you are calling via interop.
+13. We use PascalCasing for all method names, including local functions.
+14. We use ```nameof(...)``` instead of ```"..."``` whenever possible and relevant.
+15. Fields should be specified at the top within type declarations.
+16. When including non-ASCII characters in the source code use Unicode escape sequences (\uXXXX) instead of literal characters. Literal non-ASCII characters occasionally get garbled by a tool or editor.
+17. When using labels (for goto), indent the label one less than the current indentation.
+18. When using a single-statement if, we follow these conventions:
+    - Never use single-line form (for example: `if (source == null) throw new ArgumentNullException("source");`)
+    - Using braces is always accepted, and required if any block of an `if`/`else if`/.../`else` compound statement uses braces or if a single statement body spans multiple lines.
+    - Braces may be omitted only if the body of *every* block associated with an `if`/`else if`/.../`else` compound statement is placed on a single line.
+19. Make all internal and private types static or sealed unless derivation from them is required.  As with any implementation detail, they can be changed if/when derivation is required in the future.
+20. XML docs should be used when writing interfaces or when a class/method is deemed sufficient in scope or complexity.
+21. So-called [Magic Numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)) should be defined as named constants before use (for example `for (int i = 56; i < 68; i++)` could read `for (int i = _currentAge; i < _retireAge; i++)`). 
+    This may be ignored for trivial or syntactically common statements.
+
+An [EditorConfig](https://editorconfig.org "EditorConfig homepage") file (`.editorconfig`) has been provided at the root of the runtime repository, enabling C# auto-formatting conforming to the above guidelines.
+
+### Example File:
+
+``ShaderCache.cs:``
+
+```C#
+using Ryujinx.Common.Configuration;
+using Ryujinx.Common.Logging;
+using Ryujinx.Graphics.GAL;
+using Ryujinx.Graphics.Gpu.Engine.Threed;
+using Ryujinx.Graphics.Gpu.Engine.Types;
+using Ryujinx.Graphics.Gpu.Image;
+using Ryujinx.Graphics.Gpu.Memory;
+using Ryujinx.Graphics.Gpu.Shader.DiskCache;
+using Ryujinx.Graphics.Shader;
+using Ryujinx.Graphics.Shader.Translation;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
+
+namespace Ryujinx.Graphics.Gpu.Shader
+{
+    /// <summary>
+    /// Memory cache of shader code.
+    /// </summary>
+    class ShaderCache : IDisposable
+    {
+        /// <summary>
+        /// Default flags used on the shader translation process.
+        /// </summary>
+        public const TranslationFlags DefaultFlags = TranslationFlags.DebugMode;
+
+        private readonly struct TranslatedShader
+        {
+            public readonly CachedShaderStage Shader;
+            public readonly ShaderProgram Program;
+
+            public TranslatedShader(CachedShaderStage shader, ShaderProgram program)
+            {
+                Shader = shader;
+                Program = program;
+            }
+        }
+        ...
+
+        /// <summary>
+        /// Processes the queue of shaders that must save their binaries to the disk cache.
+        /// </summary>
+        public void ProcessShaderCacheQueue()
+        {
+            // Check to see if the binaries for previously compiled shaders are ready, and save them out.
+
+            while (_programsToSaveQueue.TryPeek(out ProgramToSave programToSave))
+            {
+                ProgramLinkStatus result = programToSave.HostProgram.CheckProgramLink(false);
+
+                if (result != ProgramLinkStatus.Incomplete)
+                {
+                    if (result == ProgramLinkStatus.Success)
+                    {
+                        _cacheWriter.AddShader(programToSave.CachedProgram, programToSave.BinaryCode ?? programToSave.HostProgram.GetBinary());
+                    }
+
+                    _programsToSaveQueue.Dequeue();
+                }
+                else
+                {
+                    break;
+                }
+            }
+        }
+    }
+}
+```
+
+For other languages, our current best guidance is consistency. When editing files, keep new code and changes consistent with the style in the files. For new files, it should conform to the style for that component. If there is a completely new component, anything that is reasonably broadly accepted is fine.
diff --git a/docs/workflow/pr-guide.md b/docs/workflow/pr-guide.md
new file mode 100644
index 0000000000..cc2c5900b8
--- /dev/null
+++ b/docs/workflow/pr-guide.md
@@ -0,0 +1,56 @@
+# Pull Request Guide
+
+## Contributing Rules
+
+All contributions to Ryujinx/Ryujinx repository are made via pull requests (PRs) rather than through direct commits. The pull requests are reviewed and merged by the maintainers after a review and at least two approvals from the core development team.
+
+To merge pull requests, you must have write permissions in the repository.
+
+## Quick Code Review Rules
+
+* Do not mix unrelated changes in one pull request. For example, a code style change should never be mixed with a bug fix.
+* All changes should follow the existing code style. You can read more about our code style at [docs/coding-guidelines](../coding-guidelines/coding-style.md).
+* Adding external dependencies is to be avoided unless not doing so would introduce _significant_ complexity. Any dependency addition should be justified and discussed before merge.
+* Use Draft pull requests for changes you are still working on but want early CI loop feedback. When you think your changes are ready for review, [change the status](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request) of your pull request.
+* Rebase your changes when required or directly requested. Changes should always be commited on top of the upstream branch, not the other way around.
+* If you are asked to make changes during the review process do them as a new commit.
+* Only resolve GitHub conversations with reviewers once they have been addressed with a commit, or via a mutual agreement.
+
+## Pull Request Ownership
+
+Every pull request will have automatically have labels and reviewers assigned. The label not only indicates the code segment which the change touches but also the area reviewers to be assigned.
+
+If during the code review process a merge conflict occurs, the PR author is responsible for its resolution. Help will be provided if necessary although GitHub makes this easier by allowing simple conflict resolution using the [conflict-editor](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github).
+
+## Pull Request Builds
+
+When submitting a PR to the `Ryujinx/Ryujinx` repository, various builds will run validating many areas to ensure we keep developer productivity and product quality high. These various workflows can be tracked in the [Actions](https://github.com/Ryujinx/Ryujinx/actions) tab of the repository. If the job continues to completion, the build artifacts will be uploaded and posted as a comment in the PR discussion.
+
+## Review Turnaround Times
+
+Ryujinx is a project that is maintained by volunteers on a completely free-time basis. As such we cannot guarantee any particular timeframe for pull request review and approval. Weeks to months are common for larger (>500 line) PRs but there are some additional best practises to avoid review purgatory.
+
+* Make the reviewers life easier wherever possible. Make use of descriptive commit names, code comments and XML docs where applicable.
+* If there is disagreement on feedback then always lean on the side of the development team and community over any personal opinion.
+* We're human. We miss things. We forget things. If there has been radio silence on your changes for a substantial period of time then do not hesitate to reach out directly either with something simple like "bump" on GitHub or a directly on Discord.
+
+To re-iterate, make the review as easy for us as possible, respond promptly and be comfortable to interact directly with us for anything else.
+
+## Merging Pull Requests
+
+Anyone with write access can merge a pull request manually when the following conditions have been met:
+
+* The PR has been approved by two reviewers and any other objections are addressed.
+    * You can request follow up reviews from the original reviewers if they requested changes.
+* The PR successfully builds and passes all tests in the Continuous Integration (CI) system. In case of failures, refer to the [Actions](https://github.com/Ryujinx/Ryujinx/actions) tab of your PR.
+
+Typically, PRs are merged as one commit (squash merges). It creates a simpler history than a Merge Commit. "Special circumstances" are rare, and typically mean that there are a series of cleanly separated changes that will be too hard to understand if squashed together, or for some reason we want to preserve the ability to dissect them.
+
+## Blocking Pull Request Merging
+
+If for whatever reason you would like to move your pull request back to an in-progress status to avoid merging it in the current form, you can turn the PR into a draft PR by selecting the option under the reviewers section. Alternatively, you can do that by adding [WIP] prefix to the pull request title.
+
+## Old Pull Request Policy
+
+From time to time we will review older PRs and check them for relevance. If we find the PR is inactive or no longer applies, we will close it. As the PR owner, you can simply reopen it if you feel your closed PR needs our attention.
+