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:
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 outputlint
- checks the source code for style violationsbuild
- compiles a web version of alphaTab using the current code statebuild-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 compilationtest
- Runs the unit test suite in Chrometest-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 statebuild-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.