Developer's Guide - dcs-liberation/dcs_liberation GitHub Wiki

Welcome to the dev guide !

Technical sum up

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.

Project history

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+

Required tools

When you install Python, make sure to install pip for dependencies management. This should come preinstalled.

Checkout the repository code with git

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.

Creating a Python virtual environment

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: virtualenv project settings

Running from sources

Windows terminal (using git-bash)

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

OS X terminal

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.

Running from PyCharm

You can run DCS Liberation from source with this configuration: (Adapt it to your env)

PyCharm run configuration

Type checkers and linters

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.

Making a release

Release Process

Pull requests

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.