aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
author Spartan322 <Megacake1234@gmail.com>2023-09-07 22:06:30 +0200
committer Spartan322 <Megacake1234@gmail.com>2023-09-25 00:12:48 +0200
commit60b62e370ee566010f88e65df3981125dc17be2d (patch)
tree48e2b2d22cea391ca4b653a8fd2a351657f1b630 /docs
parenta579fa30b9faced48499028f32e3ae53d7eeb142 (diff)
Simplify README.md
Add system-requirements.md Add using-git-bisect.md Add run-build-export.md Add cloning.md Add debugging.md Add rebasing.md Includes PR squashing Simplify .vscode/launch.json
Diffstat (limited to 'docs')
-rw-r--r--docs/contribution/cloning.md22
-rw-r--r--docs/contribution/debugging.md12
-rw-r--r--docs/contribution/rebasing.md66
-rw-r--r--docs/contribution/run-build-and-export.md31
-rw-r--r--docs/contribution/system-requirements.md81
-rw-r--r--docs/contribution/using-git-bisect.md24
6 files changed, 236 insertions, 0 deletions
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