Skip to main content

Contributing

We're happy to hear that you want to contribute to alphaTab. There are many ways to contribute to alphaTab. You can report bugs, request features or actually start contributing to the alphaTab source code.

Get Involved​

If you are using alphaTab in your project, you might encounter easter eggs (aka. bugs) or have the need for new features that do not exist yet in alphaTab.

For bugs, create an issue on our repository at GitHub. In case you want to request a feature, improvement or need general assistance, GitHub Discussions can be used as forum to reach out to the community.

info

Please follow the templates and do not just delete all information and drop in a 1 liner question. It is very important to get all the information asked in the template to judge the importance and content of the request. 2 minutes effort on your side, reduces heavily the effort on our side. We will close any issue not following the templates.

Join the Code​

You're a developer? You want to contribute code to alphaTab? Awesome! alphaTab is developed on GitHub using a GitFlow alike branching strategy.

The main new development happens on develop and new features are usually developed on feature/{feature or issue name}. To get started you can fork alphaTab into your account, and start preparing a fix/feature there in the style you prefer. Then just open a pull request. If you're experienced with Git and GitHub you know the drill ;)

License​

alphaTab is developed under MPL-2.0 and any source code you contribute you agree that you transfer the ownership of your change to alphaTab. By this we do not want to "take away" your change, but we want to keep the freedom to potentially change the license to something more open or different (e.g. MIT) without the need of checking with hundreds of people if this change is possible. Of course we also would not make such a change without discussing it publicly before.

A primary goal is to keep alphaTab a free an open source library for anyone to integrate.

Toolchain​

You're still here? That sounds very promising. You have made your fork, you cloned the repo and now you would be ready to start developing. But how is the big question. Before we actually touch the code it is helpful to understand the toolchain we have in alphaTab.

AlphaTab has a long history on the language it uses for developing. After all these years alphaTab ended up using TypeScript as the main language it is developed in. This change happened in April 2020. Before that AlphaTab was developed in C# with a special toolchain that ended up with JavaScript code via Haxe.

The .net version of alphaTab is still provided via a special Compiler based on the TypeScript compiler. It translates the TypeScript source code to C# from where it is compiled further.

Which brings me to the next aspect of alphaTab development. It aims for zero dependency and cross platform / language usage. The main modules of alphaTab are written as standalone source code without 3rd party dependencies and with a style that allows execution on any potential platform with a garbage collector built in (.net, JavaScript, Kotlin/Java,...). It is an active strategy to provide a platform native solution to any major platform on the market.

Development Environment​

The main development can happen with any Web focused IDE or Editor. It is up to you to decide which one you would like to use. We recommend Visual Studio Code.

Beside the IDE you will need following tools:

After that you can run the following commands to get a compiled version of alphaTab in the output folder:

> npm install
> npm start

NPM Scripts​

The repository has a set of NPM scripts that take over actions like compiling and testing. Execute them via npm run <script name>. Refer to the npm documentation for more details.

  • clean - cleans all output
  • lint - checks the source code for style violations

Web​

  • build - compiles a web version of alphaTab using the current code state
  • build-ci - compiles a web version of alphaTab using the current code state (used by GitHub Actions)
  • start - used during development time to build alphaTab quickly via watchers and incremental compilation
  • test - Runs the unit test suite in Chrome
  • test-ci - Runs the unit test suite in Chrome Headless (used by GitHub Actions)

C#/.net​

  • generate-csharp - Translates the TypeScript codebase to C#
  • build-csharp - compiles a C#/.net version of alphaTab using the current code state
  • build-csharp-ci - compiles a C#/.net version of alphaTab using the current code state (used by GitHub Actions)
  • test-csharp - runs the unit test suite for C#
  • test-csharp-ci - runs the unit test suite for C# (used by GitHub Actions)

Kotlin​

  • generate-kotlin - Translates the TypeScript codebase to Kotlin
  • build-kotlin - compiles a Kotlin version of alphaTab using the current code state
  • build-kotlin-ci - compiles a Kotlin version of alphaTab using the current code state (used by GitHub Actions)
  • test-kotlin - runs the unit test suite for Kotlin
  • test-kotlin-ci - runs the unit test suite for Kotlin (used by GitHub Actions)

Project Structure​

  • dist/

    Contains the compile output.

  • font/

    Contains the text and sound fonts that alphaTab needs for operation.

  • img/

    Contains some images for the repository.

  • node_modules/

    Contains the downloaded NPM dependencies needed during development time.

  • playground/

    Contains a template for the local playground to use during development time. It contains some sample files which can be opened in the browser for testing.

  • scripts/

    Contains scripts for the continuous integration.

  • src/

    Contains the main source code of alphaTab.

  • src.compiler/

    Contains the special source code which extends the TypeScript compiler. The whole TypeScript to C# compiler lives here but also some transformers which generate things like the JSON serializer.

  • src.csharp/

    Contains the C# specific source code which is needed on top of the generated code from TypeScript.

  • test/

    Contains the source code related to automated tests (unit tests, integration tests, visual regression tests, ...).

  • test-data/

    Contains all files needed during the tests.

  • karma.conf.js

    This is the input file for Karma, the test runner we use.

  • rollup.config.js

    This is the main configuration for Rollup.js, the bundler we use.

  • rollup.resolve.js

    A custom rollup plugin to handle module resolving.

  • tsconfig.base.json

    The main tsconfig valid for all compilations.

  • tsconfig.build.json

    The tsconfig which produces the production output (no tests).

  • tsconfig.build-csharp.json

    The tsconfig used when compiling TypeScript to C#.

  • tsconfig.build-kotlin.json

    The tsconfig used when compiling TypeScript to Kotlin.

  • tsconfig.json

    The tsconfig used during development and testing containing the main sources and tests.

  • tslint.json

    The code style rules.