Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
176 lines (119 loc) · 9.6 KB

CONTRIBUTING.md

File metadata and controls

176 lines (119 loc) · 9.6 KB

Contributing

First of all, thanks for contributing!

This document provides some basic guidelines for contributing to this repository. To propose improvements, feel free to submit a PR or open an issue.

Found a bug?

For any urgent matters (such as outages) or issues concerning the Datadog service or UI, contact our support team through https://docs.datadoghq.com/help/ for direct assistance.

To submit a bug report concerning the Datadog Unity SDK, open a GitHub Issue. Use the appropriate template and provide all listed details to help us resolve the issue.

Prerequisites

To work on the Datadog Unity SDK, you'll need to:

Android prerequisites

To build the SDK for Android:

  • In Unity Hub, ensure that all relevant Unity Editor installs include the Android Build Support components, along with OpenJDK and Android SDK & NDK Tools.
  • For Android emulator support in scripts, install the Android SDK and the cmdline-tools package.
    • To verify the SDK has successfully installed, check that $ANDROID_HOME is set, and $ANDROID_HOME/cmdline-tools/latest exists.

iOS prerequisites

To build the SDK for iOS:

  • In Unity Hub, ensure that all relevant Unity Editor installs include the iOS Build Support component.
  • Install Xcode.
    • To verify Xcode successfully installed, run: xcodebuild -version
  • Ensure that you've configured Xcode for automatic signing by authenticating with your Apple ID.
  • Install xcbeautify via brew install xcbeautify
    • To verify xcbeautify successfully installed, run: xcbeautify --version
  • Ensure that you have Ruby installed on your system.
    • To verify Ruby successfully installed, run: ruby --version, gem --version

Troubleshooting iOS Resolver

Ruby is required by External Dependency Manager for Unity (EDM4U) when targeting iOS in Unity projects. EDM4U uses Ruby to install the cocoapods gem, which it then uses to manage iOS dependencies during the build process.

EDM4U can sometimes fail to resolve the pod binary that it installs. If you get errors about CocoaPods within Unity (in a window titled "iOS Resolver"), try the following workaround:

  • Verify that pod has been installed: pod --version
    • If it's not installed, run: gem install cocoapods --user-install
  • Symlink the pod binary to one of the hardcoded search paths used by EDM4U:
    • Run sudo ln -s $(which pod)
  • Restart Unity.

Repository overview

The following instructions describe how to develop and test changes to the Datadog Unity SDK itself. For instructions on adding Datadog SDK functionality to your own Unity project, see the documentation in the DataDog/unity-package repository.

At a high level, the dd-sdk-unity repository is organized like so:

  • samples/: Unity projects used for running tests and showcasing example usage.
  • test_scaffolds/: Additional Unity projects used to test compatibility with a wider range of Unity versions.
  • tools/mock_server/: Flask app used by integration tests to record HTTP requests sent by the SDK and validate expected usage.
  • tools/scripts/: Python scripts used to automate common development tasks.
  • packages/Datadog.Unity/: The source of the Datadog Unity package, which is deployed to the root of the unity-package repo.

To get started, open samples/Datadog Sample in Unity 2023, then open the same project in your IDE of choice to begin editing the source of the Datadog.Unity package.

Running tests locally

The Datadog SDK includes a suite of tests in packages/Datadog.Unity/Tests. All significant code changes to the SDK must have adequate test coverage.

When you open a pull request, your changes are validated exhaustively against our CI pipeline. As you work, though, it's helpful to run tests locally as well.

Unity versions

We currently run tests against these versions of Unity:

Test Suite Unity Project Unity Version
unit_test test_scaffolds/2021 LTS Unity 2021.3
unit_test samples/Datadog Sample Unity 2022.3
unit_test test_scaffolds/6000 LTS Unity 6000.1
integration_test samples/Datadog Sample Unity 2022.3

Our test scripts use the Unity Hub binary to locate and manage installed versions of the Unity Editor. If a test script is unable to locate the required version of the editor, it exits with an error.

To install the latest release of a specific editor version, along with all required components for testing the Datadog SDK, you can use the install_unity script:

# Install the latest version release of Unity 2022.3 through Unity Hub
./run-script install_unity 2022.3

Unit tests

The unit_test script runs all tests except for those in the Integration namespace.

# Run Datadog SDK unit tests against the default 'Datadog Sample' project, with Unity 2022
./run-script unit_test

# Run the same tests in the '6000 LTS' project, with any version of Unity 6
./run-script unit_test --project 'test_scaffolds/6000 LTS' --unity-version 6000

# Run the same tests in the '2021 LTS' project, requiring an exact Unity 2021 build
./run-script unit_test --project 'test_scaffolds/2021 LTS' --unity-version 2021.3.44f1

When you run any of these commands from the root of this repository, the script locates the appropriate version of the Unity Editor, then boots a headless instance of that editor. That editor instance runs EditMode tests, then PlayMode tests, and then it exits.

Note: If you already have the target project open in Unity, test scripts will fail to run, as Unity does not permit the same project to be open in multiple editor instances. If you wish to run unit tests without closing the editor, you can run them directly through (Window → General → Test Runner).

Unit test results are written in JUnit format to unit-test-<mode>.xml. If all tests pass, the script will exit with a status code of 0.

Integration tests

The integration_test script runs all tests in the Integration namespace.

# Run integration tests on Android, using an AVD
./run-script integration_test --platform android

# Run integration tests on iOS, using a physically-connected iPhone
./run-script integration_test --platform ios --target device

As with the unit test script, these commands launch the Unity Editor in headless mode to invoke the tests, but the integration test script also performs some additional setup:

  • It launches a mock server that records all incoming HTTP requests from the SDK and allows the test to inspect and validate the set of requests received.
  • It configures the Unity project to use that mock server in lieu of the Datadog intake endpoint, while also ensuring that the project's Datadog settings are configured with the expected feature set.
  • It ensures that the tests run on supported platforms (Android or iOS), thereby exercising the client functionality of the underlying Android and iOS SDKs.

Integration test results are written in JUnit format to integration-test-<platform>.xml. If all tests pass, the script will exit with a status code of 0.

Debugging integration tests

Running integration tests manually is not trivial, given the extra setup steps that are handled by the script. If you want to manually recreate the integration test environment:

  • Start a mock server with ./run-script init_mock_server --start --port 5000
  • Configure the Unity project's Datadog Settings with a Custom Endpoint URL
  • Ensure that the remaining Datadog Settings match the values specified through DatadogRuntimeConfig in integration_test.py
  • If desired, start a simulator with ./run-script start_simulator --platform android