Getting Started with Development

About 3 min

Getting Started with Development

Introduction to GitHub Pull Request flow

I don't know programming but just want to modify some JSON files/documents, how can I do it?

Welcome to the GitHub Pull Request Tutorial that anyone can understand (purely web-based on Github.com)

I can program, but I've never used GitHub/C++/..., what can I do?

If you have forked this repository a long time ago, please go to Settings, scroll down to the bottom, and click Delete Repository.
Go to MAA main repository and click Fork, then Create fork.
Clone the dev branch of the (forked) repository to local with submodules:
```
git clone --recurse-submodules <link to your forked repo> -b dev
```
If you are using a Git GUI such as Visual Studio that does not include --recurse-submodules, do git submodule update --init after cloning to clone the submodules.
Download pre-built third-party libraries
A Python environment is required; please search for a Python installation tutorial if needed.
```
python maadeps-download.py
```
Configure development environment
1. Download and install Visual Studio 2022 Community. During installation, select Desktop development with C++ and .NET Desktop Development.
Double-click to open the file MAA.sln. Visual Studio will load the project automatically.
Run a build to test whether the development environment has been configured correctly. Choose Release & x64, right-click MaaWpfGui to set it as the startup project, and run it. If the build is successful, the MaaWpfGui window will appear. You can connect to the emulator in order to confirm again that the development environment has been configured correctly.
Now you are free to contribute to MAA.
Remember to commit once you have proper number of changes. Don't forget to write a commit message.
If you are a beginner of git, you might want to make changes on a newly created branch instead of committing to dev directly
```
git branch your_own_branch
git checkout your_own_branch
```
so that your new commits would grow on the new branch, without being interrupted by updates of dev
After development, push your local changes to the remote (your own repository).
```
git push origin dev
```
Go to MAA repository and submit a Pull Request. Wait until the administrator approves it. Please note that the changes should be based on dev instead of master branch, and should be merged to dev branch as well.
When there are changes from other contributors on upstreaming MAA repository, it might be necessary for you to add them to your own branch.
1. Add MAA upstream repository.
```
git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
```
2. Fetch upstream changes from the repository.
```
git fetch upstream
```
3. rebase (recommended) or merge changes.
```
git rebase upstream/dev
```
  or
```
git merge
```
4. Repeat step 7-10.

Note: operations regarding Git can be done by VS2022 instead of command line tools, using the Git changes tab.

MAA file formatting requirements

MAA uses a series of formatting tools to ensure that the code and resource files in the repository are visually unified for easy maintenance and reading.

Please ensure that it has been formatted before submission, or enable Pre commit Hooks for automatic formatting.

The currently enabled formatting tools are as follows:

File Type	Format Tool
C++	clang-format
Json/Yaml	Prettier
Markdown	markdownlint

Use Pre-commit Hooks to Automatically Format Code

Ensure that you have Python and Node environments on your computer.
Execute the following command in the root directory of the project:
```
pip install pre-commit
pre-commit install
```

If pre-commit still cannot be used after pip install, please check if the pip installation path has been added to the PATH.

The formatting tool will automatically run every time you submit to ensure that your code format conforms to the style guide.

Enable clang-format in Visual Studio

Install clang-format version 17 or higher.
```
python -m pip install clang-format
```
Use tools like 'Everything' to locate the installation location of clang-format.exe. As a reference, if you are using Anaconda, clang-format.exe will be installed in YourAnacondaPath/Scripts/clang-format.exe.
In Visual Studio, search for 'clang-format' in Tools-Options.
Click Enable ClangFormat support and select Use custom clang-format.exe file and choose the clang-format.exe located in Step 2.

You are all set with the clang-format integrated in Visual Studio supporting c++20 features!

You can also format with tools\ClangFormatter\clang-formatter.py directly, by executing in the root folder of the project:

python tools\ClangFormatter\clang-formatter.py --clang-format=PATH\TO\YOUR\clang-format.exe --input=src\MaaCore

Develop in cloud using GitHub codespace

Create GitHub codespace with pre-configured C++ dev environments:

Then follow the instructions in vscode or Linux tutorial to configure GCC 12 and the CMake project.