Developer's Guide
Welcome to the dev guide !
DCS Liberation is coded in Python, with QT6 as UI framework. It uses pyDCS to generate DCS World missions.
Before contributing to DCS Liberation, you should also maybe consider contributing to PyDCS, this is a great way to contribute indirectly to the project.
DCS Liberation was a project started in 2018 by shdwp, original repo is still available here : https://github.com/shdwp/dcs_liberation
The original UI was different, and the mission generation process was different as well from version 2.0+
- Python 3.11
- A code Editor for Python. I recommend PyCharm Community Edition, you can add plugin for Lua.
When you install Python, make sure to install pip for dependencies management. This should come preinstalled.
Branches
- master : Should be even with current release version
- develop : Current version being worked on, might be unstable
The following instructions work for the git command line. If using the GitHub Desktop or gh tools, the steps will be the same but the exact commands will differ.
To get started with development, run:
git clone https://github.com/dcs-liberation/dcs_liberation.git
This will automatically check out the develop branch.
Please see Pull requests for instructions on which branch should be targeted with PRs.
A Python virtual environment (virtualenv) is a local copy of the Python distribution for a specific project. This allows you to install the project dependencies local to the environment rather than globally on your system, which makes it easier to reset your environment if something goes wrong.
To create and use a virtualenv, run:
cd dcs_liberation
python -m venv env
.\env\Scripts\activate
pip install -r requirements.txt
pre-commit install
The first line creates the virtualenv to the directory env. The second line replaces the python for the current shell with the one in the virtualenv. The third line installs the project's dependencies. The final line installs the pre-commit hooks to run the auto-formatter on commit.
Whenever you open a new terminal, you'll need to re-run .\env\Scripts\activate.
If you're using PyCharm, you can configure the project to use your virtualenv in the project settings: 
If you run from sources for the first time, you need to build the frontend, otherwise you won't be able to see the map. For the frontend to build, you need npm installed, which you can get on the Node.js webpage. After installing node.js and npm, do the following for the first build:
cd client
npm install
npm run build
Every time you update the repo you should rebuild the front-end:
cd client
npm run build
If you're not developing the front-end (or the API boundary) that's enough. Otherwise, see client/README.md.
Set up your virtual env (described above), activate your env, then:
PYTHONPATH=. python ./qt_ui/main.py
Set up your virtual env (described above), activate your env, then:
PYTHONPATH=. LOCALAPPDATA=. python ./qt_ui/main.py
The LOCALAPPDATA=. environment variable will result in settings files being put in a sub folder in your local dev directory.
You can run DCS Liberation from source with this configuration: (Adapt it to your env)
We use black for auto-formatting. The pre-commit hook will automatically run the formatter when you make a commit. See their docs for instructions on configuring black to run in your editor.
We use mypy for type checking. Python has built-in support for type annotations but does not perform any checking; that work is delegated to tools like mypy. All new code should include type annotations, and it's generally a good idea to add type annotations to any function you touch.
To check for type errors, run:
mypy game
This only checks the game package. qt_ui will probably never be checkable because PySide2 (the Python Qt API) contains many patterns that do not play well with the type checker, but it's good to add the annotations anyway as they help the reader.
The type checker is not run as part of pre-commit, since that makes it harder to create WIP commits, but is run as a part of the PR and build checks, so it's best to run before uploading a PR, and definitely should be run before a push to develop.
Please make a new branch from either develop or master, and make your pull requests to dcs-liberation/develop.
We can only merge/revert whole PRs, which means you should try and keep the size of each individual PR as small as possible. Ideally, one PR for one feature/bugfix/change. Also, review latency doesn't scale linearly with review time, and review time doesn't scale linearly with PR complexity. Smaller PRs will likely get reviewed sooner and faster. In addition, it's not possible for the testers to isolate bugs on a sub-build level.
New features and bug fixes in pull requests are usually worth mentioning in the changelog. Exceptions are fixes for bugs that never shipped (were only present in a canary build), and changes with no intended user observable behavior, such as a refactor. If you're comfortable writing the note yourself, add it to changelog.md in the root of the project in the section for the upcoming release.
If you're new to GitHub, https://guides.github.com/introduction/flow/ and the other tutorials on that site may be helpful.