CONTRIBUTING.md

Contributing

Issues

With bugs and problems, please try to describe the issue as detailed as possible to help us reproduce it.

Pull Requests

Before creating a pull request, please

• Make sure all guidelines are followed
• Make sure your branch is free of merge conflicts

Development workflow

To get started with the project, run yarn bootstrap in the root directory to install the required dependencies for each package and cocoapods dependencies for the example app:

yarn bootstrap

While it's possible to use npm, the tooling is built around yarn, so you'll have an easier time if you use yarn for development.

While developing, you can run the example app to test your changes. Any changes you make in your library's JavaScript code will be reflected in the example app without a rebuild. If you change any native code, then you'll need to rebuild the example app.

To start the packager, run in the root directory:

yarn example start

To build and run the example app on Android:

yarn example android

To build and run the example app on iOS:

yarn example ios

To edit the Swift/Objective-C files, open example/ios/BitmovinPlayerReactNativeExample.xcworkspace in Xcode and find the source files at Pods > Development Pods > RNBitmovinPlayer.

To edit the Kotlin files, open example/android in Android Studio and find the source files at bitmovin-player-react-native under Android.

For iOS/tvOS on-device development

To build the example project for an iOS or tvOS device, you need to create a file at example/ios/Developer.xcconfig. In this file, add your development team like this:

DEVELOPMENT_TEAM = YOUR_TEAM_ID

TypeScript Code Style

• Follow the eslint rules (yarn lint). They are enforced automatically via a pre-commit git hook.
• Always add return values to functions (even if void)
• No unused imports
• Public functions should be documented with a description that explains what it does
• Every code block that does not obviously explain itself should be commented with an explanation of why and what it does

Linting

Typescript

ESLint, Prettier, TypeScript

We use TypeScript for type checking, ESLint with Prettier for linting and formatting the code, and Jest for testing.

Our pre-commit hooks verify that the linter will pass when committing. Make sure your code passes TypeScript and ESLint. Run the following to verify:

yarn typescript
yarn lint

To fix formatting errors, run the following:

yarn lint --fix

Kotlin

For Kotlin code ktlint is used with ktlint gradle plugin. Run the following inside android folder to verify code format:

./gradlew ktlintCheck

To fix formatting errors, run the following inside android folder:

./gradlew ktlintFormat

You can add a lint check pre-commit hook by running inside android folder:

./gradlew addKtlintCheckGitPreCommitHook

and for automatic pre-commit formatting:

./gradlew addKtlintFormatGitPreCommitHook

Swift

For Swift code SwiftLint is used. To install SwiftLint, run brew bundle install in the root directory. Our pre-commit hooks verify that the linter will pass when committing.

To verify Swift code, run the following:

swiftlint

To fix auto-fixable SwiftLint violations, run the following:

swiftlint lint --autocorrect

Testing

Remember to add tests for your change if possible. Run the player tests by:

yarn integration-test test:android
yarn integration-test test:ios

To set the license key to be used for the tests, you can set the key "licenseKey" in integration_test/app.json.

See available API for testing here.

Adding new tests

To add new tests:

1. create a new file in the specs/ folder.
2. import the new file to the specs/index.ts file and add it to the default exported array.

A Player Test has the following structure always:

export default (spec: TestScope) => {
  spec.describe('SCENARIO TO TEST', () => {
    spec.it('EXPECTATION', async () => {
      await startPlayerTest({}, async () => {
        // TEST CODE
      });
    });
  });
};

For example:

export default (spec: TestScope) => {
  spec.describe('playing a source', () => {
    spec.it('emits TimeChanged events', async () => {
      await startPlayerTest({}, async () => {
        await loadSourceConfig({
          url: 'https://bitmovin-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8',
          type: SourceType.HLS,
        });
        await callPlayerAndExpectEvents((player) => {
          player.play();
        }, EventSequence(EventType.Play, EventType.Playing));
        await expectEvents(RepeatedEvent(EventType.TimeChanged, 5));
      });
    });
  });
};

Scripts

The package.json file contains various scripts for common tasks:

• yarn bootstrap: setup the whole project by installing all dependencies and pods.
• yarn bootstrap:example: setup example project by installing all dependencies and pods.
• yarn bootstrap:integration-test: setup integration tests project by installing all dependencies and pods.
• yarn build: compile TypeScript files into lib/ with ESBuild.
• yarn typescript: type-check files with TypeScript.
• yarn lint: lint files with ESLint.
• yarn format: format files with Prettier.
• yarn docs: generate documentation with TypeDoc.
• yarn brew: install all dependencies for iOS development with Homebrew.
• yarn example start: start the Metro server for the example app.
• yarn example android: run the example app on Android.
• yarn example pods: install pods only.
• yarn integration-test start: start the Metro server for the integration tests.
• yarn integration-test test:android: run the player tests on Android emulator.
• yarn integration-test test:ios: run the player tests on iOS simulator.
• yarn integration-test pods: install pods only.
• yarn example ios: run the example app on iOS.