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.

We accept all kind of requests via GitHub just open a new issue by choosing one of the templates and filling it out with your request.

important

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 effor on our side. We will close any issue not following the templates.

Join our Gitter Chatroom

If you just have a general question or need assistance our Gitter chatroom might be also a good way to get in contact. We just lately openeg this room so do not hesitate to ask there even though it feels a bit empty there ;)

https://gitter.im/alphaTabMusic/community

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 not new to 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 this years alphaTab ended up using TypeScript as the main language it is developed in. This change happend 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:

• Node.js
• .net Core SDK

After that you can run the following commands and should have already 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 <scriptname>. Refer to the npm documentation for more details.

• clean - cleans all output
• lint - checks the source code for style violations
• build - compiles a web version of alphaTab using the current code state
• build-ci - usedcompiles 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)
• 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)

Project Structure

• dist/

  Contains the compile output.

• font/

  Contains the text and soundfounts 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 atemplate 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.json

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

• tslint.json

  The code style rules.