From 60b62e370ee566010f88e65df3981125dc17be2d Mon Sep 17 00:00:00 2001 From: Spartan322 Date: Thu, 7 Sep 2023 16:06:30 -0400 Subject: 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 --- .vscode/launch.json | 12 ++--- README.md | 23 +++++---- docs/contribution/cloning.md | 22 +++++++++ docs/contribution/debugging.md | 12 +++++ docs/contribution/rebasing.md | 66 +++++++++++++++++++++++++ docs/contribution/run-build-and-export.md | 31 ++++++++++++ docs/contribution/system-requirements.md | 81 +++++++++++++++++++++++++++++++ docs/contribution/using-git-bisect.md | 24 +++++++++ 8 files changed, 251 insertions(+), 20 deletions(-) create mode 100644 docs/contribution/cloning.md create mode 100644 docs/contribution/debugging.md create mode 100644 docs/contribution/rebasing.md create mode 100644 docs/contribution/run-build-and-export.md create mode 100644 docs/contribution/system-requirements.md create mode 100644 docs/contribution/using-git-bisect.md 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 `. 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 = use commit +# r, reword = use commit, but edit the commit message +# e, edit = use commit, but stop for amending +# s, squash = use commit, but meld into previous commit +# f, fixup [-C | -c] = 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 = run command (the rest of the line) using shell +# b, break = stop here (continue rebase later with 'git rebase --continue') +# d, drop = remove commit +# l, label