Contributing to GitHub for Unity

Build Requirements

This repository is LFS-enabled. To clone it, you should use a git client that supports git LFS 2.x and submodules.

Windows

Visual Studio 2015+ or Mono 4.x + bash shell (git bash).
- Mono 5.x will not work
UnityEngine.dll and UnityEditor.dll.
- If you've installed Unity in the default location of C:\Program Files\Unity or C:\Program Files (x86)\Unity, the build will be able to reference these DLLs automatically. Otherwise, you'll need to copy these DLLs from [Unity installation path]\Unity\Editor\Data\Managed into the lib directory in order for the build to work

MacOS

Mono 4.x required. You can install it via brew with brew tap shana/mono && brew install mono@4.8
- Mono 5.x will not work
UnityEngine.dll and UnityEditor.dll.
- If you've installed Unity in the default location of /Applications/Unity, the build will be able to reference these DLLs automatically. Otherwise, you'll need to copy these DLLs from [Unity installation path]/Unity.app/Contents/Managed into the lib directory in order for the build to work

How to Build

Clone the repository and its submodules in a git GUI client that supports Git LFS, or via the command line with the following command:

git lfs clone https://github.com/github-for-unity/Unity

Note: git might complain that it can't checkout the script submodule. That submodule is not required for normal builds and you can ignore the error, or run the following to stop it complaining:

git submodule deinit script

Important pre-build steps

The build needs to reference UnityEngine.dll and UnityEditor.dll. These DLLs are included with Unity. If you've installed Unity in the default location, the build will be able to find them automatically. If not, copy these DLLs from [your Unity installation path]\Unity\Editor\Data\Managed into the lib directory in order for the build to work.

Developer OAuth app

Because GitHub for Unity uses OAuth web application flow to interact with the GitHub API and perform actions on behalf of a user, it needs to be bundled with a Client ID and Secret.

For external contributors, we have bundled a developer OAuth application in the source so that you can complete the sign in flow locally without needing to configure your own application.

These are listed in src/GitHub.Api/Application/ApplicationInfo.cs

DO NOT TRUST THIS CLIENT ID AND SECRET! THIS IS ONLY FOR TESTING PURPOSES!!

The limitation with this developer application is that this will not work with GitHub Enterprise. You will see sign-in will fail on the OAuth callback due to the credentials not being present there.

To provide your own Client ID and Client Secret:

Register a new developer application in your profile.
Copy common/ApplicationInfo_Local.cs-example to common/ApplicationInfo_Local.cs and fill out the clientId/clientSecret fields for your application.

Visual Studio

To build with Visual Studio 2015+, open the solution file GitHub.Unity.sln. Select Build Solution in the Build menu.

Mono and Bash (windows and mac)

To build with Mono 4.x and Bash, first ensure Mono is added to PATH. Mono installs to C:\Program Files\Mono\bin\ by default. Then execute build.sh in a bash shell.

Build Output

Once you've built the solution for the first time, you can open src/UnityExtension in Unity. This folder contains the GitHub.Unity project and all the Unity UI and other Unity-specific code that you can have Unity compile as normal for quick testing and prototyping.

The build also creates a Unity test project called GitHubExtension inside a directory called github-unity-test next to your local clone. For instance, if the repository is located at c:\Projects\Unity the test project will be at c:\Projects\github-unity-test\GitHubExtension. You can use this project to test binary builds of the extension in a clean environment (all needed DLLs will be copied to it every time you build).

Note: some files might be locked by Unity if have one of the build output projects open when you compile from VS or the command line. This is expected and shouldn't cause issues with your builds.

Solution organization

The GitHub.Unity.sln solution includes several projects:

packaging: empty projects with build rules that copy DLLs to various locations for testing
Tests: unit and integration test projects
GitHub.Logging: A logging helper library
GitHub.Api: The core of the extension. This project is C#6 and includes async/await threading and other features that Unity cannot currently compile.
GitHub.Unity: Unity-specific code. This project is compilable by Unity