Merge branch 'main' of https://github.com/game-ci/documentation into …

…standalone

README.md

@@ -1,50 +1,88 @@
-# GameCI
+<p align="center">
+ <img height=200px src="static/assets/images/logo-cropped.png">
+<p>
 
-Documentation for open source GameCI projects. You can find the `.md` files inside the
-[docs](./docs) folder. The live version is available on [game.ci](https://game.ci). This website is
-built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+<p align="center">
+ <a href="https://discord.com/invite/WyPN5r9">
+ <img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white"></a>
+ <a href="https://opencollective.com/game-ci">
+ <img src="https://img.shields.io/badge/OpenCollective-1F87FF?style=for-the-badge&logo=OpenCollective&logoColor=white"></a> <br>
+ <img src="https://img.shields.io/github/license/game-ci/documentation.svg">
+ <img src="https://img.shields.io/github/stars/game-ci/documentation.svg">
+ <img src="https://img.shields.io/github/last-commit/game-ci/documentation.svg">
+<p>
 
-### Installation
+<br>
 
-```bash
-yarn
-```
+## Welcome
 
-### Local Development
+Welcome to the GameCI documentation repo! Here you will find the documentation assests for GameCI
+and it's related open-source projects. The live documentation site availble at
+<a href="https://game.ci">game.ci</a>.
 
-```bash
-yarn start
-```
+You may also view the markdown files directly at the following links:
 
-This command starts a local development server and opens up a browser window. Most changes are
-reflected live without having to restart the server.
+- [Getting Started with GameCI](docs/02-getting-started)
+- [Github Actions](docs/03-github)
+- [Gitlab Pipelines](docs/05-gitlab)
+- [CircleCi<](docs/11-circleci)
+- [Docker](docs/08-docker)
+- [Github Cloud Runner](docs/03-github-cloud-runner)
+- [Troubleshooting](docs/09-troubleshooting)
+- [FAQ](docs/10-faq)
 
-### Build
+## Building the Docs Site
 
-```bash
-yarn build
-```
+Built with [Docusaurus 2.](https://docusaurus.io/)
 
-This command generates static content into the `build` directory and can be served using any static
-contents hosting service.
+This project has a hard dependancy on Node16. You will need to make sure that you have the proper
+version of node installed to avoid errors.
 
-## Community
+- [Install Node16 on Ubuntu](https://joshtronic.com/2021/05/09/how-to-install-nodejs-16-on-ubuntu-2004-lts/)
+- [Install Node16 using brew](https://apple.stackexchange.com/a/207883)
 
-Feel free to join us on [![Discord](static/assets/readme/Discord.svg)](https://game.ci/discord) and
-engage with the community.
+This project relies on yarn for package management. You will need to install yarn in order to build
+and test the documentation site.
 
-## Support us
+- [Official yarn installation docs.](https://classic.yarnpkg.com/lang/en/docs/install)
 
-GameCI is free for everyone forever.
+1. Install project dependancies
 
-You can support us at [OpenCollective](https://opencollective.com/game-ci).
+ ```bash
+ yarn install
+ ```
 
-## Licence
+2. Start a local develpment server
+
+ This command starts a local development server and opens up a browser window. Most changes are
+ reflected live without having to restart the server.
+
+ ```bash
+ yarn start
+ ```
+
+3. Create a build This command generates static content into the `build` directory and can be
+ served using any static contents hosting service.
+
+ ```bash
+ yarn build
+ ```
 
-This repository is [MIT](./LICENSE) licensed.
+## Meet the Community
+
+Join us on [Discord](https://game.ci/discord) and engage with the growing community of engineers,
+artists, hobbyists, and professionals using GameCI to build, test, and publish their projects
+everyday.
+
+## Support the Team
+
+GameCI is free for everyone forever. You can support the peolpe who make GameCI pssible on
+[OpenCollective](https://opencollective.com/game-ci)
+
+## Licence
 
-This includes all contributions from the community.
+This repository is [MIT](./LICENSE) licensed. This includes all contributions from the community.
 
 ## Sponsors
 
-[![CircleCI](static/assets/readme/CircleCI.svg)](https://circleci.com?utm_source=game-ci)
+<img src="https://img.shields.io/badge/Vercel-000000?style=for-the-badge&logo=vercel&logoColor=white" href="https://vercel.com?utm_source=game-ci">

docs/03-github/03-test-runner.mdx

@@ -74,6 +74,81 @@ Example of use:
 
 That is all you need to test your project.
 
+## Testing Unity packages
+
+The test runner offers basic support for testing Unity packages, with [a few caveats](#caveats).
+
+### Additional setup
+
+After performing [Basic setup](#basic-setup), three extra steps are required for testing Unity
+packages.
+
+#### Setting packageMode
+
+To indicate that the test runner is being run for a Unity package rather than a Unity project, set
+the [`packageMode`](#packagemode) configuration option to `true`.
+
+```yaml
+- uses: game-ci/unity-test-runner@v2
+ with:
+ packageMode: true
+```
+
+#### Passing a unityVersion
+
+Make sure that you explicitly pass the [`unityVersion`](#unityversion) argument, as it's necessary
+for the test runner to test Unity packages.
+
+```yaml
+- uses: game-ci/unity-test-runner@v2
+ with:
+ unityVersion: [your desired Unity version]
+```
+
+See the [GitHub Issue](https://github.com/game-ci/unity-test-runner/issues/227) for more details on
+why this is necessary.
+
+#### Choosing a package directory
+
+Make sure that the directory of the package being tested is **not** the same as the repository's
+root directory. This condition will cause the test runner to hang and fail.
+
+Currently, the only known workarounds for this failure are these two options:
+
+1. Restructure your repository to place the package being tested in a subdirectory of the
+ repository's root directory.
+2. Somehow temporarily move the package being tested to a subdirectory of the repository's root
+ directory within the GitHub Workflow where you're using the test runner.
+
+Whichever workaround you choose, make sure that the [`projectPath`](#projectpath) corresponds to
+wherever the package being tested is located at the time the test runner is called in your GitHub
+Workflow.
+
+See the [GitHub Issue](https://github.com/game-ci/unity-test-runner/issues/223) for more details and
+potential workarounds.
+
+### Caveats
+
+- As stated above, the action will fail if the directory of the package being tested is the same as
+ the root directory of the repository (this issue is being tracked
+ [here](https://github.com/game-ci/unity-test-runner/issues/223)).
+- As stated above, excluding `unityVersion` or passing a `unityVersion` configuration of `auto` when
+ testing a Unity package will cause the test runner to fail. The Unity version must be manually set
+ in the configuration options (this issue is being tracked
+ [here](https://github.com/game-ci/unity-test-runner/issues/227)).
+- The test runner can only test packages on Linux runners - Windows runners are currently not
+ supported (this issue is being tracked
+ [here](https://github.com/game-ci/unity-test-runner/issues/224))
+- Packages with dependencies outside of the Unity Registry have not been tested an may or may not
+ work with the test runner (this issue is being tracked
+ [here](https://github.com/game-ci/unity-test-runner/issues/225)).
+- There is currently no caching set up for the testing of Unity packages (this issue is being
+ tracked [here](https://github.com/game-ci/unity-test-runner/issues/226)).
+- If using the [`customImage`](#customImage) parameter to use a custom Docker image to test the
+ package, that image must have [`jq`](https://jqlang.github.io/jq/) installed, or else the test
+ runner will error. It is used to add the package being tested to a temporary Unity project's
+ package manifest at runtime.
+
 ## Viewing test results
 
 The test results can be viewed from a
@@ -170,20 +245,25 @@ To do so, simply add Github Actions' official
 
 This simple addition could speed up your test runs by more than 50%.
 
+Note that caching in this manner only applies to testing Unity **Projects**, not Unity **Packages**
+(see [Caveats](#caveats)).
+
 ## Configuration options
 
 Below options can be specified under `with:` for the `unity-test-runner` action.
 
 #### unityVersion
 
 Version of Unity to use for testing the project. Use "auto" to get from your
-ProjectSettings/ProjectVersion.txt
+ProjectSettings/ProjectVersion.txt. ⚠️ If testing a Unity Package, this field is required and cannot
+be set to "auto".
 
 _**required:** `false`_ _**default:** `auto`_
 
 #### customImage
 
-Specific docker image that should be used for testing the project.
+Specific docker image that should be used for testing the project. If packageMode is true, this
+image must have [`jq`](https://jqlang.github.io/jq/) installed.
 
 ```yaml
 - uses: game-ci/unity-test-runner@v2
@@ -195,8 +275,8 @@ _**required:** `false`_ _**default:** `""`_
 
 #### projectPath
 
-Specify the path to your Unity project to be tested. The path should be relative to the root of your
-project.
+Specify the path to your Unity project or package to be tested. The path should be relative to the
+root of your project.
 
 _**required:** `false`_ _**default:** `<your project root>`_
 
@@ -257,6 +337,9 @@ definition to manage scripts, see Unity's documentation on
 [Assembly definitions](https://docs.unity3d.com/2022.2/Documentation/Manual/ScriptCompilationAssemblyDefinitionFiles.html)
 for how to create and manage assembly definitions.
 
+To get coverage when testing a package, make sure you pass assemblies from the package you want
+covered to the `assemblyFilters` option.
+
 _**required:** `false`_ _**default:**
 `generateAdditionalMetrics;generateHtmlReport;generateBadgeReport`_
 
@@ -311,6 +394,19 @@ unity versions.
 
 _**required:** `false`_ _**default:** `Test Results`_
 
+#### packageMode
+
+Whether the tests are being run for a Unity package instead of a Unity project.
+
+If true, the action can only be run on Linux runners, and any custom docker image passed to this
+action must have [`jq`](https://jqlang.github.io/jq/) installed.
+
+NOTE: may not work properly for packages with dependencies outside of the Unity Registry.
+
+See [Testing Unity packages](#testing-unity-packages) for more information.
+
+_**required:** `false`_ _**default:** `false`_
+
 ## Complete example
 
 A complete workflow that tests all modes separately could look like this:
@@ -365,3 +461,54 @@ jobs:
  name: Coverage results for ${{ matrix.testMode }}
  path: ${{ steps.tests.outputs.coveragePath }}
 ```
+
+## Complete Example (Testing a Package)
+
+A complete workflow that tests all modes separately (for a package rather than a project) could look
+like this:
+
+```yaml
+name: Test package
+
+on: [push, pull_request]
+
+jobs:
+ testAllModes:
+ name: Test in ${{ matrix.testMode }}
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ projectPath:
+ - test-package
+ unityVersion: '2020.3.0f1' # some version must be included for package testing
+ testMode:
+ - playmode
+ - editmode
+ steps:
+ - uses: actions/checkout@v2
+ with:
+ lfs: true
+ - uses: game-ci/unity-test-runner@v2
+ id: tests
+ env:
+ UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
+ with:
+ projectPath: ${{ matrix.projectPath }}
+ unityVersion: ${{ matrix.unityVersion }}
+ testMode: ${{ matrix.testMode }}
+ artifactsPath: ${{ matrix.testMode }}-artifacts
+ githubToken: ${{ secrets.GITHUB_TOKEN }}
+ checkName: ${{ matrix.testMode }} Test Results
+ coverageOptions: 'generateAdditionalMetrics;generateHtmlReport;generateBadgeReport;assemblyFilters:+my.assembly.*'
+ - uses: actions/upload-artifact@v2
+ if: always()
+ with:
+ name: Test results for ${{ matrix.testMode }}
+ path: ${{ steps.tests.outputs.artifactsPath }}
+ - uses: actions/upload-artifact@v2
+ if: always()
+ with:
+ name: Coverage results for ${{ matrix.testMode }}
+ path: ${{ steps.tests.outputs.coveragePath }}
+```

docs/10-faq/index.mdx

@@ -33,16 +33,18 @@ interested in automation around game development.
 
 ### Recommendations for other game engines
 
-For **[Unreal Engine](https://unrealengine.com/)**, we recommend you have a look at
-[unrealcontainers](https://unrealcontainers.com) from our friend [Adam Rehn](https://adamrehn.com/).
+For **[Unreal Engine](https://unrealengine.com/)** users, it's worth checking out
+[unrealcontainers](https://unrealcontainers.com), a great resource created by our friend
+[Adam Rehn](https://adamrehn.com/).
 
-For **[Godot](https://godotengine.org/)**, there are multiple options available. We know about
-[abarichello/godot-ci](https://github.com/abarichello/godot-ci) from
-[Artur Barichello](https://barichello.me/).
+For **[Godot](https://godotengine.org/)** developers, there are several options to consider. We
+recommend both [abarichello/godot-ci](https://github.com/abarichello/godot-ci) by
+[Artur Barichello](https://barichello.me/) and
+[firebelley/godot-export](https://github.com/firebelley/godot-export).
 
-For **[MonoGame](https://www.monogame.net/)**, there is this amazing guide on
-[Lean MonoGame - Automate Release](https://learn-monogame.github.io/how-to/automate-release/) from
-[Jean-David Moisan (Apostolique)](https://jeandavidmoisan.com/)
+**[MonoGame](https://www.monogame.net/)** enthusiasts should look at
+[Lean MonoGame - Automate Release](https://learn-monogame.github.io/how-to/automate-release/), an
+excellent guide from [Jean-David Moisan (Apostolique)](https://jeandavidmoisan.com/).
 
 ## Why use GameCI for Unity?
 
@@ -302,6 +304,8 @@ The core maintainers of GameCI are:
  [Card Game Simulator](https://www.cardgamesimulator.com/) and Software Engineer at
  [JPMorgan Chase & Co](https://www.jpmorganchase.com/).
 
+See [About us](https://game.ci/about) for more details.
+
 [unity-docker-versions]: /docs/docker/versions
 [discord]: https://game.ci/discord
 [common-issues]: /docs/troubleshooting/common-issues