Update CONTRIBUTING.md

.github/ISSUE_TEMPLATE/bug_report.md

@@ -13,12 +13,12 @@ assignees: ''
 ## Version of spice2x
 *version of spice, this can be seen in the About tab, and in log.txt*
 
-## Laptop
-*Are you running this on a laptop? Does it have a hybrid iGPU+ dGPU configuration?*
+*please remember to test the LATEST beta version before posting a bug about it**
+
+## Describe the issue
+*what's the issue?*
 
 ## Attached log.txt file, if available
 > [!WARNING]
 > Please make sure you remove any personally identifiable information from the log file.
-
-## Describe the issue
-*what's the issue?*
+> Please set `-loglevel` to `all` before launching the game for more verbose logs.

.github/ISSUE_TEMPLATE/patch-submission.md

@@ -10,6 +10,7 @@ assignees: ''
 > [!NOTE]
 > Before submitting code changes... 
 > * Please do note that this is a GPL v3.0 open source project.
+> * Please read the [CONTRIBUTING](https://github.com/spice2x/spice2x.github.io/blob/main/CONTRIBUTING.md) guide.
 > * Maintainers reserve the right to reject or modify your submission without reason.
 > * If accepted, your github user name will be credited on the main web page, and then archived in the [past versions wiki page](https://github.com/spice2x/spice2x.github.io/wiki/Past-versions-and-change-log)
 > 

CONTRIBUTING.md

@@ -9,6 +9,18 @@ Baseline rules for patch submissions are as follows. Any patches violating the r
 * For a new game that was never supported (not a new version of a game, but rather a new series): please wait 1 year after official AC release in Japan.
 * For new version of an already supported game: proceed with caution and use generally-accepted community guidelines.
 
+### Avoiding regressions
+
+The biggest risk in making code changes to spice is the risk of regressions. There is a **lot** of shared code used by many different games, reaching back game versions that are more than a decade old. It is practically impossible to test all supported games and versions.
+
+Additionally, there's a lot of code that get exercised on specific hardware - including hardware that you probably don't have access to (e.g., ICCA reader, real cabinet I/O, specific model of a IIDX controller, particular brand of touch screens...)
+
+Therefore, when making code changes, please be extremely careful about containing / scoping your changes. Make targeted bug fixes scoped to handful of game versions and hardware configuration. When adding new features, make it off by default, unless there is a really good reason to make it the default. If you make a new default, add an option that disables it so that users can opt out as needed.
+
+#### Config file compatibility
+
+Do not change the names of options, buttons binds, analogs, etc - since they are used as unique identifiers in config files. If they are changed, you will introduce an incompatibility with previous versions of config file.
+
 ### Code quality requirements
 
 * Test for regressions, at least in and around the component you are modifying:
@@ -19,4 +31,57 @@ Baseline rules for patch submissions are as follows. Any patches violating the r
 * Make sure you compile with the included Docker script and ensure you do not introduce **any** new compiler warnings or build breaks. The Docker script is the standard build environment, your custom Linux build environment or MSVC can be used during development, but you must validate the final build using Docker.
 * Do not submit snippets of code as a "patch". Exceptions can be made for trivial changes (correct a typo, fix a single line of code...), but otherwise, a successfully compiled & fully tested patch file is required when submitting for review.
 * Do not make code changes in unrelated areas; i.e., do not run code linters and auto-formatters for parts of the code that you didn't modify.
-  * Note: there are no strict rules for code formatting, but please attempt to emulate the style around the code you are modifying.
+* Try to submit smaller chunks of code, instead one gigantic patch. For example, don't submit a patch for "Improve feature XYZ"; instead, submit "Change how A works to prepare for feature XYZ" "Refactor B for feature XYZ" "Add feature B to enable feature XYZ".
+* Write to the log for anything useful - it helps immensely with debugging post-mortem. At the same time though, avoid spamming the log for something trivial.
+
+### UI text
+spice2x has a global audience; majority of the user base do not speak English as their first language.
+
+Use simple English, avoid colloquialism, and use concise language, even if it's slightly technical.
+
+### Using OS APIs
+
+Avoid making permanent changes to user's OS configuration. For example, spice should not make a call to set power profile to Maximum Performance, or switch default audio device. Making the reverse call to restore settings on game shutdown is **not** good enough; there is no guarantee that spice will gracefully shutdown, since games (or spice) can crash. This is to avoid inadvertently putting user's PC into a bad state, which can be seen as malware-like behavior.
+
+Watch out for legacy OS compatibility. Currently, the minimum support floor is Windows 7. If you use any Windows API, make sure it's supported in Windows 7. If you need to use API that is not present in Windows 7, you must not directly link against it, otherwise spice will fail to launch on older OSes. Take a look at Windows 8 touch code (win8.cpp) for examples on how to discover OS APIs via pointers.
+
+### Code style requirements
+* Indents are four spaces.
+* Always use \{ curly braces \} when appropriate; do not omit them even when it's optional; such as `for` `if` `else`, etc.
+
+OK:
+```c
+if (conditional) {
+    DoSomething();
+}
+```
+
+Not OK:
+```c
+if (conditional)
+    DoSomething();
+```
+
+Not OK:
+```c
+if (conditional) DoSomething();
+```
+
+* Opening curly braces should appear at the end, not in a line on its own.
+
+OK:
+```c
+if (conditional) {
+    DoSomething();
+}
+```
+
+Not OK:
+```c
+if (conditional)
+{
+    DoSomething();
+}
+```
+
+* Other than that, there are no strict rules for code formatting, but please attempt to emulate the style around the code you are modifying.

README.md

@@ -4,13 +4,15 @@
 
 # 🌶️🌶️ [https://spice2x.github.io/](https://spice2x.github.io/) 🌶️🌶️
 
+# If you have problems, read [Known Issues (FAQ)](https://github.com/spice2x/spice2x.github.io/wiki/Known-issues) wiki page first, most of your questions are already answered.
+
 <br/><br/><br/><br/><br/><br/><br/><br/>
 
 # spice2x
 
 ## Overview
 
-spice2x is a fork of SpiceTools, focused on addressing bugs, usability, and quality-of-life improvements.
+spice2x is a continuation of SpiceTools project. Original development of [SpiceTools](https://github.com/spicetools/spicetools) has stalled in 2022; spice2x is led by a new group of developers.
 
 We do not use GitHub for source control, but we do use the [issue tracker](https://github.com/spice2x/spice2x.github.io/issues) and [the wiki](https://github.com/spice2x/spice2x.github.io/wiki). Source is distributed in the release package.
 
@@ -20,17 +22,31 @@ spice2x team does not provide any tools to circumvent software copy protection,
 
 [List of supported games](https://github.com/spice2x/spice2x.github.io/wiki/List-of-supported-games)
 
+## How do I set up game data & start playing?
+
+By policy,
+
+* we do **NOT** provide links on where to acquire game data
+* we do **NOT** provide tools or instructions on decrypting data
+* we do **NOT** provide guides on setting up & basic troubleshooting
+
+please do not ask for these, as it will never happen here.
+
 ## Submitting to the Issue Tracker
+
+**Please file bugs if you find them!** If you just complain about something in Discord servers, we can't see them, so they'll never be fixed.
+
 Rules for filing a new issue or adding comments to existing issues in the tracker:
 
-* Check the [known issues](https://github.com/spice2x/spice2x.github.io/wiki/Known-issues) page first before reporting a new issue.
+* Check the [known issues](https://github.com/spice2x/spice2x.github.io/wiki/Known-issues) page first before reporting a new issue. If you have some new information or workarounds for a known issue, you can file a documentation bug as well.
 * Use the search function and see if there is an existing issue. 
-* This is not the place to ask about other projects, especially EA servers. Bad servers can (and will) crash your game.
-* **Do not link to external websites that distribute game data!**
+* This is not the place to obtain a guide or receive basic troubleshooting.
+* Don't file a bug demanding game XYZ to be supported.
+* **Do not upload game data - any part of it, XML files included!**
+* **Do not mention or link to external websites that distribute game data!**
+* **Do not link to external websites that provide guides on how to run games!**
 
-New GitHub accounts are prevented from creating new issues to prevent spam.
-
-Maintainers of this project reserve the right to close or delete any low effort issues.
+New GitHub accounts are prevented from creating new issues to prevent spam. Maintainers of this project reserve the right to close or delete any issues that violate the rules above, or any low effort issues. If you ask for very basic troubleshooting help with setting up a game, we'll just delete them without warning.
 
 ## Contributing
 **We encourage the community to submit patches via the issue tracker for any bug fixes or feature enhancements.** If you want to resolve any reported (or not reported) bugs, implement features, add support for new games, or fix a [known issue](https://github.com/spice2x/spice2x.github.io/wiki/Known-issues) - feel free to reach out via the Issue tracker. All submitted code patches are assumed to be GPLv3 compliant.