From 33f1a43e8b725b5b8a98e50a72ffd118efc9b2e7 Mon Sep 17 00:00:00 2001 From: Cilliers Pretorius <41905461+Pietersielie@users.noreply.github.com> Date: Fri, 18 Oct 2024 13:49:27 +0200 Subject: [PATCH 1/6] Create DEVELOP.md Add a description of development practices. --- DEVELOP.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 DEVELOP.md diff --git a/DEVELOP.md b/DEVELOP.md new file mode 100644 index 00000000..3e61b75c --- /dev/null +++ b/DEVELOP.md @@ -0,0 +1,18 @@ +# Developing for iDaVIE +## Development environment + * Unity + * Powershell + * Set up UnityYamlMerge. + * [Jetbrains](https://www.jetbrains.com/rider/) or [VSCode](https://code.visualstudio.com/) + * Debugging on [Jetbrains](https://www.jetbrains.com/help/rider/Debugging_Unity_Applications.html) or [VSCode](https://marketplace.visualstudio.com/items?itemName=visualstudiotoolsforunity.vstuc) +## Merging procedure +Merging two branches of a Unity project can be problematic and very time consuming. We list the steps to follow when merging two branches. + * Switch to the target branch of iDaVIE with `git switch `. + * Merge with `git merge --no-commit `, where remote is the branch to be merged into the current branch. + * If any conflict in script files occur, resolve using your mergetool of choice (we recommend VSCode or a derivative thereof). + * Once all script file conflicts are resolved, resolve scene file conflicts (if any exist) using UnityYamlMerge. + * Run `git mergetool` to run UnityYaml with the settings set up earlier. + * If a temporary file conflicts, select the `current` option and complete the merge. + * Test the final merged result. +## Testing regime + * [User testing](https://docs.google.com/forms/d/e/1FAIpQLSf-gYZtDUkB3AV8zIZWm9QQ4w7NSWaDnXPDGA5uS65Yo5uVcw/viewform?usp=sf_link) From 3b5ec1fb9cb03a178ebf567d408803ccd1210b40 Mon Sep 17 00:00:00 2001 From: Cilliers Pretorius <41905461+Pietersielie@users.noreply.github.com> Date: Mon, 21 Oct 2024 10:27:39 +0200 Subject: [PATCH 2/6] Update DEVELOP.md --- DEVELOP.md | 47 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 33 insertions(+), 14 deletions(-) diff --git a/DEVELOP.md b/DEVELOP.md index 3e61b75c..4478ff3c 100644 --- a/DEVELOP.md +++ b/DEVELOP.md @@ -1,18 +1,37 @@ # Developing for iDaVIE ## Development environment - * Unity - * Powershell - * Set up UnityYamlMerge. - * [Jetbrains](https://www.jetbrains.com/rider/) or [VSCode](https://code.visualstudio.com/) - * Debugging on [Jetbrains](https://www.jetbrains.com/help/rider/Debugging_Unity_Applications.html) or [VSCode](https://marketplace.visualstudio.com/items?itemName=visualstudiotoolsforunity.vstuc) +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 = '\\Unity\\2021.3.47f1\\Editor\\Data\\Tools\\UnityYAMLMerge.exe' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED" + trustExitCode = false +[merge] + tool = UnityYamlMerge +``` + 2. In the folder `\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. We list the steps to follow when merging two branches. - * Switch to the target branch of iDaVIE with `git switch `. - * Merge with `git merge --no-commit `, where remote is the branch to be merged into the current branch. - * If any conflict in script files occur, resolve using your mergetool of choice (we recommend VSCode or a derivative thereof). - * Once all script file conflicts are resolved, resolve scene file conflicts (if any exist) using UnityYamlMerge. - * Run `git mergetool` to run UnityYaml with the settings set up earlier. - * If a temporary file conflicts, select the `current` option and complete the merge. - * Test the final merged result. +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 `. + 2. Merge with `git merge --no-commit `, 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 regime [checklist](https://forms.gle/ezLXLHeWR4ZeLmfz7). ## Testing regime - * [User testing](https://docs.google.com/forms/d/e/1FAIpQLSf-gYZtDUkB3AV8zIZWm9QQ4w7NSWaDnXPDGA5uS65Yo5uVcw/viewform?usp=sf_link) +We provide a testing regime [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). From cbd05a909b7f4043dd3c6aaded3c34c56c66bcf2 Mon Sep 17 00:00:00 2001 From: Cilliers Pretorius <41905461+Pietersielie@users.noreply.github.com> Date: Mon, 21 Oct 2024 10:31:57 +0200 Subject: [PATCH 3/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 696a951f..38c03f56 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,13 +6,13 @@ 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. @@ -20,8 +20,8 @@ If you would like to add a feature or fix a bug yourself, feel free to look thro 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/) From 94051894a5bffcf7d72329673827900800e48d41 Mon Sep 17 00:00:00 2001 From: Cilliers Pretorius <41905461+Pietersielie@users.noreply.github.com> Date: Mon, 21 Oct 2024 10:32:47 +0200 Subject: [PATCH 4/6] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 53d83985..0b5465f1 100644 --- a/README.md +++ b/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). From 4c2d4198901a27182308c3887eb3d7e3c589f9c8 Mon Sep 17 00:00:00 2001 From: Cilliers Pretorius <41905461+Pietersielie@users.noreply.github.com> Date: Tue, 22 Oct 2024 10:09:57 +0200 Subject: [PATCH 5/6] Update DEVELOP.md --- DEVELOP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DEVELOP.md b/DEVELOP.md index 4478ff3c..6e93c89f 100644 --- a/DEVELOP.md +++ b/DEVELOP.md @@ -32,6 +32,6 @@ Merging two branches of a Unity project can be problematic and very time consumi 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 regime [checklist](https://forms.gle/ezLXLHeWR4ZeLmfz7). + 7. Test the final merged result using the testing protocol [checklist](https://forms.gle/ezLXLHeWR4ZeLmfz7). ## Testing regime -We provide a testing regime [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). +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). From 572eca10b6ee94155fbfee085e3d14943dc1d67c Mon Sep 17 00:00:00 2001 From: Cilliers Pretorius <41905461+Pietersielie@users.noreply.github.com> Date: Wed, 30 Oct 2024 10:19:43 +0200 Subject: [PATCH 6/6] Update DEVELOP.md --- DEVELOP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEVELOP.md b/DEVELOP.md index 6e93c89f..62eadbbc 100644 --- a/DEVELOP.md +++ b/DEVELOP.md @@ -10,7 +10,7 @@ They are both fully functional, and considerably more lightweight than Visual St * [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. +To facilitate the merging of separate branches that include merge conflicts in scene (`*.unity`) files 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"]