Merge pull request #156 from Spartan322/fixup/docs

8 files changed, 251 insertions, 20 deletions

diff --git a/.vscode/launch.json b/.vscode/launch.json
index 2cabcf6..8fd62de 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -8,18 +8,14 @@
             "type": "cppdbg",
             "request": "launch",
             "name": "Debug",
-            "program": "/bin/godot4",   // TODO: Godot environment variable?
-            "args": [],
+            "program": "/bin/godot4", // TODO: Set your Godot binary path
+            "args": [
+                "-e"
+            ],
             "cwd": "${workspaceFolder}/game",
             "preLaunchTask": "dev_build",
             "windows": {
-                "type": "cppvsdb",
-                "request": "launch",
-                "name": "Debug",
-                "program": "/bin/godot4", // TODO: Common Godot 4 Windows install or Godot environment variable?
-                "args": [],
                 "cwd": "${workspaceFolder}\\game",
-                "preLaunchTask": "dev_build",
             }
         }
     ]
diff --git a/README.md b/README.md
index 2f93ebe..792ff61 100644
--- a/README.md
+++ b/README.md
@@ -4,15 +4,19 @@ Main Repo for the OpenVic Project
 ## Quickstart Guide
 For detailed instructions, view the Contributor Quickstart Guide [here](docs/contribution-quickstart-guide.md)
 
-## Required
+## System Requirements
 * [Godot 4.1.1](https://github.com/godotengine/godot/releases/tag/4.1.1-stable)
 * [scons](https://scons.org/)
 
+See [System Requirements](docs/contribution/system-requirements.md).
+
 ## Repo Setup
 1. Clone the OpenVic Repo to a suitable folder using the git command `git clone https://github.com/OpenVicProject/OpenVic.git`
 2. Update the submodules by executing the git command `git submodule update --init --recursive`
 
-Note that using a zip download instead of cloning means a lot of work in manually managing submodules individually. It is strongly recommended to use git to obtain the source code. 
+Note that using a zip download instead of cloning means a lot of work in manually managing submodules individually. It is strongly recommended to use git to obtain the source code.
+
+See [Cloning](docs/contribution/cloning.md).
 
 ## [Godot Documentation](https://docs.godotengine.org/en/latest/)
 
@@ -24,16 +28,7 @@ Note that using a zip download instead of cloning means a lot of work in manuall
 5. Press "Import & Edit", wait for the Editor to finish re-importing assets, and then close the Editor ***without saving*** and reopen the project.
 6. Once loaded, click the play button at the top right, and you should see and hear the game application open on the main menu.
 
-## Build/Run Instructions for Archlinux (using yay)
-1. Install [Godot 4.1.1](https://archlinux.org/packages/extra/x86_64/godot/)  with `yay -S Godot` and [scons](https://archlinux.org/packages/extra/any/scons/) with ` yay -S scons`.
-2. Clone the OpenVic Repo using the git command `git clone https://github.com/OpenVicProject/OpenVic.git`.
-3. CD into the game directory with `cd ./OpenVic`.
-4. Update the submodules by executing the git command `sudo git submodule update --init --recursive`.
-5. While still in the game directory, run `scons`.
-6. Now launch Godot 4, click import and navigate to `OpenVic` then to `game`.
-7. Click `project.godot`.
-5. Press "Import & Edit", wait for the Editor to finish re-importing assets, and then close the Editor ***without saving*** and reopen the project.
-6. Once loaded, click the play button at the top right, and you should see and hear the game application open on the main menu.
+See [Run, Build, and Export](docs/contribution/run-build-export.md).
 
 ## Project Export
 1. Build the extension with `scons` or `scons target=template_debug`. (or `scons target=template_release` for release)
@@ -47,8 +42,12 @@ Note that using a zip download instead of cloning means a lot of work in manuall
     * On Windows run `game/export/Windows/OpenVic.exe`.
     * On Linux x86_64 run `game/export/Linux-x86_64/OpenVic.sh`.
 
+See [Run, Build, and Export](docs/contribution/run-build-export.md).
+
 ## Extension Debugging
 1. If in a clean build, build the extension with `scons`.
 2. Build with `scons dev_build=yes`.
 3. [Setup your IDE](https://godotengine.org/qa/108346/how-can-i-debug-runtime-errors-of-native-library-in-godot) so your Command/Host/Launching App is your Godot 4 binary and the Working Directory is the `game` directory.
 4. Start the debugger.
+
+See [Debugging](docs/contribution/debugging.md).
diff --git a/docs/contribution/cloning.md b/docs/contribution/cloning.md
new file mode 100644
index 0000000..06a84bb
--- /dev/null
+++ b/docs/contribution/cloning.md
@@ -0,0 +1,22 @@
+# Cloning
+
+If you do not have Git installed foremost you need to install it at https://git-scm.com/download.
+
+Once installed you need to clone OpenVic:
+```sh
+git clone https://github.com/OpenVicProject/OpenVic.git
+```
+After cloning you must initialize and update the submodules:
+```sh
+cd OpenVic
+git submodule update --init --recursive
+```
+Updating the submodules is neccessary every time the dependencies are updated, if you're unsure, on every `git pull` you should also call `git submodule update --init --recursive`
+
+To update the repo you must pull the repo:
+```sh
+git pull
+```
+Git may install a gui with it, this gui can be a useful external tool for doing things related to git, (especially commits) you can open it via `git gui`.
+
+Further tutorials and documentation on git can be found at https://git-scm.com/book.
\ No newline at end of file
diff --git a/docs/contribution/debugging.md b/docs/contribution/debugging.md
new file mode 100644
index 0000000..e788c44
--- /dev/null
+++ b/docs/contribution/debugging.md
@@ -0,0 +1,12 @@
+# Debugging
+
+For debugging, foremost you must:
+
+1. Build the extension with dev_build, it is also recommended to include debug_symbols. To do so run `scons dev_build=yes debug_symbols=yes`.
+
+2. Attach a debugger to Godot:
+    * For VSCode this has been mostly setup for you, in `.vscode/launch.json` just set `configuration.program` to your Godot binary path.
+
+    * For Visual Studio: TODO
+
+3. Run the task with the debugger attached.
\ No newline at end of file
diff --git a/docs/contribution/rebasing.md b/docs/contribution/rebasing.md
new file mode 100644
index 0000000..31d53bb
--- /dev/null
+++ b/docs/contribution/rebasing.md
@@ -0,0 +1,66 @@
+# Rebasing
+
+If you have haven't read the quick intro to Git see [Cloning](cloning.md) first.
+
+Sometimes our workflow will request of you to rebase/squash commits in your PRs to keep the history clean. This will be a simple intro to what we mean by rebasing/squashing.
+
+First we will start with rebasing to the master branch:
+```sh
+git fetch origin
+git rebase origin master
+```
+There may be conflicts, if you use VSCode, it has extensions to assist with dealing with conflicts. If you need more help resolving merge conflicts you can always ask more senior developers. This should however be uncommon if you keep your branch up to date.
+
+## PR Squashing
+
+On your PR you will see a Commits tab:
+
+TODO: input Commits tab image
+
+In here you will see a list of commits you've made to your PR branch, count the amount of PR commits that are not merge commits. (if you have merge commits please contact senior developers as things can get messy if you continue here) Make sure you are on your branch, you can use `git checkout <branch-name>`. The number of regular commits in your repo you can then perform a rebase, so say you have 6 commits in your PR, you can squash them down to one by doing:
+```sh
+git rebase -i HEAD~6
+```
+
+Now this will collect all commits from the HEAD (the current commit you're on) back 6 commits (including the HEAD) and rebase them into whatever you tell the dialogue. Now if you do this you might something like this in a text document or in your terminal:
+```sh
+pick 24a0751 Update README.md for Archlinux users
+pick 0e408c8 Add Window Override
+
+# Rebase 5c739f1..0e408c8 onto 5c739f1 (2 commands)
+#
+# Commands:
+# p, pick <commit> = use commit
+# r, reword <commit> = use commit, but edit the commit message
+# e, edit <commit> = use commit, but stop for amending
+# s, squash <commit> = use commit, but meld into previous commit
+# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
+#                    commit's log message, unless -C is used, in which case
+#                    keep only this commit's message; -c is same as -C but
+#                    opens the editor
+# x, exec <command> = run command (the rest of the line) using shell
+# b, break = stop here (continue rebase later with 'git rebase --continue')
+# d, drop <commit> = remove commit
+# l, label <label> = label current HEAD with a name
+# t, reset <label> = reset HEAD to a label
+# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
+#         create a merge commit using the original merge commit's
+#         message (or the oneline, if no original merge commit was
+#         specified); use -c <commit> to reword the commit message
+# u, update-ref <ref> = track a placeholder for the <ref> to be updated
+#                       to this position in the new commits. The <ref> is
+#                       updated at the end of the rebase
+#
+# These lines can be re-ordered; they are executed from top to bottom.
+#
+# If you remove a line here THAT COMMIT WILL BE LOST.
+#
+# However, if you remove everything, the rebase will be aborted.
+#
+```
+Read the comments following the `#` and it'll tell you what to do, generally we would prefer you to perform the squash action so for this, if this were a PR you would only have to do:
+```sh
+pick 24a0751 Update README.md for Archlinux users
+s 0e408c8 Add Window Override
+```
+The top value is the first commit you referred to, this list is organized according to a seqeunce of the commit history, (this specific one was made via `HEAD~2`) you will always want the first one to be pick here, generally everything else is squash/s so it merges the commit into the previous commit while still giving you control over the commit messages. After this it will rebase the commits and then ask you about the commit message you wish to create, this will have to be up to you, you can always change it later, if there is a problem with it we will mention it. Now that you've done that however, the last step is to force push it, to do so you can use `git gui` and push then click the force option or you can call `git push -f`. Now your squash is complete. Be careful rebasing or squash when someone else is working on your branchs at the same time, a force push can hurt them, you should wait until they tell you that they're done and merge their changes to your branch before you rebase/squash. Rebasing/squashing commits that others rely upon is a one-way ticket to Git nigthmares.
\ No newline at end of file
diff --git a/docs/contribution/run-build-and-export.md b/docs/contribution/run-build-and-export.md
new file mode 100644
index 0000000..99acd9a
--- /dev/null
+++ b/docs/contribution/run-build-and-export.md
@@ -0,0 +1,31 @@
+# Run, Build, and Export
+
+If you have haven't read the quick intro to Git see [Cloning](cloning.md) and [System Requirements](system-requirements.md) first.
+
+## Run
+
+With the project installed and system requirements ready:
+
+1. Run `scons` in the project root.
+    * Ensure a `game/bin/openvic/libopenvic` file is produced for your platform (windows, linux, macos)
+2. Open Godot, click import, naivgate to the `game` directory and click `Import and Edit`.
+    * Wait for the import to finish, close the editor without saving, then reopen the project in Godot.
+3. Press the play button at the top right of the editor.
+
+## Build
+* To build for debug run `scons` in the project root.
+* To build for debug with debug symbols and breakpoints run `scons dev_build=yes debug_symbols=yes` in the project root.
+* To build for release run `scons target=template_release`
+
+## Export
+1. Build `scons` with either debug or release:
+    * For debug just run `scons` or `scons target=template_debug`
+    * For release just run `scons target=template_release`
+2. Open Godot and open the project.
+3. Click `Project` at the top left and click `Export`.
+    * If you do not have templates, download and install them, wait for them to complete.
+4. Click `Export Project...`
+    * If you built all binaries, you can click `Export All` and select debug or release there.
+5. A file popup will appear, to export click `Save`:
+    * If you built scons with debug, leave `Export With Debug` ticked.
+    * Else untick `Export With Debug` for release.
\ No newline at end of file
diff --git a/docs/contribution/system-requirements.md b/docs/contribution/system-requirements.md
new file mode 100644
index 0000000..9fd7719
--- /dev/null
+++ b/docs/contribution/system-requirements.md
@@ -0,0 +1,81 @@
+# System Requirements
+
+## Build Requirements
+* [Python 3.6+](https://www.python.org/downloads/)
+* [Scons 3.0+](https://scons.org/)
+* [Godot 4](https://github.com/godotengine/godot)
+
+### Windows Requirements
+* [Visual Studio Community](https://www.visualstudio.com/vs/community/)
+* [Python 3.6+](https://www.python.org/downloads/windows/) - Ensure the installer adds Python to your PATH (you can rerun the installer to do so)
+
+#### Installing Scons
+With Python 3.6+ installed, you can install Scons through pip:
+```sh
+python -m pip install scons
+```
+If you get `Defaulting to user installation because normal site-packages is not writeable` then open a command prompt as Administrator and run the command again. When finished call:
+```
+scons --version
+```
+to ensure that you are using a correct version of Scons.
+
+#### Installing Visual Studio
+Ensure that if you install from Visual Studio 2017, 2019 or 2022, ensure you're installing the C++ tools.
+
+If you're installing Visual Studio 2015, ensure you choose custom and pick C++ as the language.
+
+### Linux Requirements
+* GCC 12.3+
+
+#### Debian/Ubuntu Linux Install
+```sh
+apt-get install \
+  build-essential \
+  scons \
+  pkg-config \
+  libx11-dev \
+  libxcursor-dev \
+  libxinerama-dev \
+  libgl1-mesa-dev \
+  libglu-dev \
+  libasound2-dev \
+  libpulse-dev \
+  libudev-dev \
+  libxi-dev \
+  libxrandr-dev
+```
+
+#### Arch Linux Requirements
+```sh
+pacman -S --needed \
+  scons \
+  pkgconf \
+  gcc \
+  libxcursor \
+  libxinerama \
+  libxi \
+  libxrandr \
+  mesa \
+  glu \
+  libglvnd \
+  alsa-lib \
+  pulseaudio
+```
+
+### macOs Requirements
+* [Xcode](https://apps.apple.com/us/app/xcode/id497799835)
+    * Clang 14+
+* [MoltenVK Vulkan SDK](https://sdk.lunarg.com/sdk/download/latest/mac/vulkan-sdk.dmg) 
+
+#### Homebrew
+```sh
+brew install scons
+```
+
+#### MacPorts
+```sh
+sudo port install scons
+```
+
+Credit: [Godot Docs](https://docs.godotengine.org/en/stable/contributing/development/compiling/index.html)
\ No newline at end of file
diff --git a/docs/contribution/using-git-bisect.md b/docs/contribution/using-git-bisect.md
new file mode 100644
index 0000000..ea6135b
--- /dev/null
+++ b/docs/contribution/using-git-bisect.md
@@ -0,0 +1,24 @@
+# Using Git Bisect
+
+Git bisect is a very useful tool for debugging issues that you can't find the root of, specifically when you know a period in the commit history where that issue did not exist.
+
+How git bisect works is by binary searching through the commit history marking commits as good or bad until you reach the history responsible for the issue at hand.
+
+To start using it you must do:
+```sh
+git bisect start
+git bisect good <GOOD COMMIT HASH>
+git bisect bad <BAD COMMIT HASH>
+```
+
+The bisect will begin, it will perform a binary search and put you at a specific commit, if the commit still has the bug then run:
+```sh
+git bisect bad
+```
+If the commit doesn't have the bug then run:
+```sh
+git bisect good
+```
+When done it will stop at the responsible commit for which you can investigate to see whats causing the issue.
+
+For more documentation on git bisect see: https://git-scm.com/docs/git-bisect
\ No newline at end of file