Add documentation on development best practices for iDaVIE

CONTRIBUTING.md

@@ -6,22 +6,22 @@ Thank you for your interest in helping iDaVIE improve. We gladly accept contribu
 There are several ways to contribute to the development of iDaVIE.
 ### Issues
 #### Create a new issue
-If you find an error with iDaVIE (e.g., the program crashing, data not loading, or incorrect behaviour), [check if a similar issue already exists](https://github.com/idia-astro/idia_unity_vr/issues). If a relevant issue does not exist already, create a new issue using one of the [relevant templates](https://github.com/idia-astro/iDaVIE/issues/new/choose).
+If you find an error with iDaVIE (e.g., the program crashing, data not loading, or incorrect behaviour), [check if a similar issue already exists](https://github.com/idia-astro/iDaVIE/issues). If a relevant issue does not exist already, create a new issue using one of the [relevant templates](https://github.com/idia-astro/iDaVIE/issues/new/choose).
 
 #### Request a feature
 If you have an idea for a new feature you feel is missing from iDaVIE, feel free to open a new issue using the feature request [template](https://github.com/idia-astro/iDaVIE/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BFR%5D+%22New+Feature+Request%22). The development team will evaluate its feasibility, and assign it a priority on the [project board](https://github.com/orgs/idia-astro/projects/2/views/1) depending on the likely difficulty of implementing it. Of course, nothing prevents you from adding the feature yourself.
 
 #### Fixing an issue
-If you would like to add a feature or fix a bug yourself, feel free to look through our [existing issues](https://github.com/idia-astro/idia_unity_vr/issues) to find one that interests you. You can filter the issues by `Label`, and we recommend issues labeled with [`"good first issue"`](https://github.com/idia-astro/idia_unity_vr/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) for developers just getting started with iDaVIE. If you have selected an issue to work on, please leave a comment on the issue saying that you've claimed it, allowing the maintainers to follow up, keep track of what is being fixed, and prioritise. Once you complete your work, please open a pull request following the [pull request template](https://github.com/idia-astro/iDaVIE/compare) and we'll integrate your fix into future releases of iDaVIE.
+If you would like to add a feature or fix a bug yourself, feel free to look through our [existing issues](https://github.com/idia-astro/iDaVIE/issues) to find one that interests you. You can filter the issues by `Label`, and we recommend issues labeled with [`"good first issue"`](https://github.com/idia-astro/iDaVIE/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) for developers just getting started with iDaVIE. If you have selected an issue to work on, please leave a comment on the issue saying that you've claimed it, allowing the maintainers to follow up, keep track of what is being fixed, and prioritise. Once you complete your work, please open a pull request following the [pull request template](https://github.com/idia-astro/iDaVIE/compare) and we'll integrate your fix into future releases of iDaVIE.
 
 #### Pull request etiquette
 1. Make sure to test a compiled version of the program before submitting a pull request, not just the version in the Unity Editor.
 2. Make sure to add documentation in the code that you wrote – we will not accept pull requests that lack documentation.
 3. Make sure to clearly list the changes you've made and why – detailed reasoning make it more likely that the pull request will be accepted.
 
 Before you start developing, please take a look at the following resources:
-* [Building iDaVIE from source](https://github.com/idia-astro/idia_unity_vr/blob/main/BUILD.md)
-* [Installing Unity and recommended development environment](https://docs.unity3d.com/hub/manual/index.html)
+* [Building iDaVIE from source](https://github.com/idia-astro/iDaVIE/blob/main/BUILD.md)
+* [Recommended development environment](https://github.com/idia-astro/iDaVIE/blob/main/DEVELOP.md)
 * [Getting started with Unity](https://docs.unity3d.com/2021.3/Documentation/Manual/index.html)
 * [Unity C# Tutorial](https://learn.unity.com/project/beginner-gameplay-scripting)
 * [iDaVIE documentation](https://idavie.readthedocs.io/en/latest/)

DEVELOP.md

@@ -0,0 +1,37 @@
+# Developing for iDaVIE
+## Development environment
+Before developing for iDaVIE, we strongly recommend that, in addition to the steps listed in the [Building from source](https://github.com/idia-astro/iDaVIE/blob/main/BUILD.md#prerequisites) document, the following steps are followed:
+### Install a code editor
+Unity will require the installation of [Visual Studio](https://visualstudio.microsoft.com/) as part of its installation, since that provides the compiler and libraries for the C# aspects of Unity. While it can serve as an IDE, we do not recommend it due to the heavy performance load it demands when in use. Instead, we recommend the following IDEs:
+  * [Jetbrains](https://www.jetbrains.com/rider/)
+  * [VSCode](https://code.visualstudio.com/)
+
+They are both fully functional, and considerably more lightweight than Visual Studio. In addition, both have good integration with the Unity Editor to allow for debugging iDaVIE while it is running. Consult the following resources on how to set up debugging a Unity project in the respective IDEs:
+  * [Debugging Unity Applications with Jetbrains](https://www.jetbrains.com/help/rider/Debugging_Unity_Applications.html)
+  * [VSCode Tools for Unity](https://marketplace.visualstudio.com/items?itemName=visualstudiotoolsforunity.vstuc)
+### Set up UnityYamlMerge
+To facilitate the merging of separate branches in iDaVIE, Unity provides a mergetool called UnityYamlMerge. This requires a few set up steps before it can be used.
+  1. First, the iDaVIE repo should be told to use UnityYamlMerge as the mergetool. Add the following lines to the `.git/commit` file. Note the escaped slash `\\` for folder divisors -- it will not work otherwise.
+```
+[mergetool "UnityYamlMerge"]
+	cmd = '<path\\to\\Unity>\\Unity\\2021.3.47f1\\Editor\\Data\\Tools\\UnityYAMLMerge.exe' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"
+	trustExitCode = false
+[merge]
+	tool = UnityYamlMerge
+```
+  2. In the folder `<path\to\Unity>\Unity\2021.3.47f1\Editor\Data\Tools`, open the `mergespecfile.txt` text file. This file contains the fallback mergetools if UnityYamlMerge cannot resolve the conflicts or filetypes. Here we recommend VSCode as the fallback. Add the following lines to the `mergespecfile.txt` file. Note that `code` is likely in the system PATH if VSCode is installed, otherwise the path of the `code.exe` executable is required.
+```
+# VSCode
+* use code --wait "%r" "%l" "b" "%d"
+```
+## Merging procedure
+Merging two branches of a Unity project can be problematic and very time consuming if scene files were changed in both branches. We list the steps to follow when merging two branches.
+  1. Switch to the target branch of iDaVIE with `git switch <target>`.
+  2. Merge with `git merge --no-commit <remote>`, where remote is the branch to be merged into the current branch.
+  3. If any conflict in script files occur, resolve using your mergetool of choice (we recommend VSCode or a derivative thereof).
+  4. Once all script file conflicts are resolved, resolve scene file conflicts (if any exist) using UnityYamlMerge.
+  5. Run `git mergetool` to run UnityYaml with the settings set up earlier.
+  6. If a temporary file conflicts, select the `current` option and complete the merge.
+  7. Test the final merged result using the testing protocol [checklist](https://forms.gle/ezLXLHeWR4ZeLmfz7).
+## Testing regime
+We provide a testing protocol [checklist](https://forms.gle/ezLXLHeWR4ZeLmfz7) that must be completed without issues before a change can be merged into the main branch. If a new feature is added, similar testing for that feature should be developed as well (i.e., how to test that feature, and what other features might be affected by it).

README.md

@@ -38,7 +38,7 @@ In order to run iDaVIE, the following software needs to be installed:
 
 ### Contributing
 Full documentation is available in our [contribution document](https://github.com/idia-astro/iDaVIE/blob/main/CONTRIBUTING.md). To summarise, we welcome contributions in the form of:
-1. Reporting bugs or requesting new features by [creating an issue](https://github.com/idia-astro/idia_unity_vr/issues).
+1. Reporting bugs or requesting new features by [creating an issue](https://github.com/idia-astro/iDaVIE/issues).
 2. Adding your own contributions through a [pull request](https://github.com/idia-astro/iDaVIE/compare).
 3. Assisting other users by participating in the [iDaVIE discussions](https://github.com/idia-astro/iDaVIE/discussions).