Contributing.md

Contributing

If you're interested in contributing to this project, please open a pull request on our GitHub repository, or send your contact information, such as your telegram account, encrypted with our GPG Key: 0x9B1380D7B700BA9DFAAED4849EEEED2D1566C61B, to the mailbox.

Also, note that this project is open-source and licensed under GPL-3.0.

Project Structure

Basic Information

This project is mainly composed of one repository, hosted on a self-built gitea server for safety and convenience reasons and push to the mirror repository on Github. Therefore, for the pull requests, we will choose to squash merge manually instead of on the Github Pull Requests Page.

The backend of the application is written in C++, the frontend in Qt/QML. The wiki website is generated by docsify.

Due to the tight coupling required by some features, basic knowledge of both C++ and Qt/QML is recommended.

• Modern C++ Tutorial: https://changkun.de/modern-cpp/
• Qt/QML: https://doc.qt.io/qt-6/
• SQLite: https://www.sqlite.org/cintro.html
• Protocol Buffers: https://developers.google.com/protocol-buffers
• gRPC: https://grpc.io/
• V2Fly Core Document: https://www.v2fly.org/

Code Style

Auto Formatting

• .clang-format

If you are using QtCreator as an IDE, then you can enable automatic formatting in the setting options. More ...

Be careful not to check the Override Clang Format configuration file box.

Also, remember to enable QML formatting.

For Visual Studio Code user, install the C/C++ extension, and enable the Editor: Format On Save option. If the .clang-format file is not found, you can use the {Key: value, ...} to set specific parameters.

QML Coding Conventions

https://doc.qt.io/qt-6/qml-codingconventions.html

Item {
    id: control // id on the first line makes it easy to find an object

    property int fontSize: 14 // `Camel-Case` property declarations

    signal acceptAll // signal declarations

    function doSomething(x) // javascript functions
    {
        return x + photoImage.width
    }

    // try to group related properties together
    width: 180 // object properties (layout properties take precedence)

    Rectangle {} // child objects

    Connections {} // special child objects

    states: State {} // states

    transitions: Transition {} // transitions
}

For complex JavaScript functions, we use TypeScript to generate and import them into QML files. More...

Naming Conventions

• Snake Case for temporary variables: auto node_info = ...;
• Hungarian notation for member variables.: Config m_config; Config* p_config;
• Camel Case for QML property and method: void getNodeInfo();

Directory Structure

.
├── 3rdpart // git submodules
├── cmake
├── CMakeLists.txt
├── i18n // translations
├── LICENSE
├── misc // icons and other static source
    ├── across_example.json
    ├── across.proto
    ├── across.rc
    ├── command.proto
    ├── design
    ├── icons
    ├── org.arktoria.across.desktop
    ├── resource.h
    ├── screenshots
    ├── v2ray_api.proto
    ├── v2ray_config.proto
    └── VERSION
├── pkgbuild
    ├── arch
    └── msys2
├── README.md
├── src
    ├── app.cpp
    ├── app.h
    ├── main.cpp
    ├── models // Processing
    ├── view_models // Data Bindings
    └── views // QML Files and Scripts
├── tests
└── vcpkg.json

Core Components

• Application

  Program entry. Providing initialization, QML object bindings, and SingleApplication.

• ConfigTools

  Processing user profile. Generating, parsing, and saving configuration according to the across.proto.

• CoreTools

  QProcess control and send the configuration to v2fly core by stdin.

• LogTools

  Core anc application logger. There are two global static logger named app and core. You can get them from spdlog::get("app") or spdlog::get("core") and clone to your component named logger. More...

• DBTools

  SQlite3 database control. Used to store node configurations and some runtime variables. You can directly open the database to get the fields.

• GroupList

  Loading GroupInfo items from the database and managing the subscription.

• NodeList

  Loading NodeInfo items by current group and managing them.

Translations

https://doc.qt.io/qt-6/internationalization.html

The translation files are located in the [${CMAKE_SOURCE_DIR}/i18n/] (https://github.com/ArkToria/ACross/tree/master/i18n) directory. And the file name should conform to the specification: across_<language code>.ts, e.g., across_zh_CN.ts.

If the translation file is not updated during the build, you can use the following command on project workspace to update it manually.

$ lupdate6 src/ -ts i18n/across_zh_CN.ts

We recommend using the Qt Linguist tool to edit the generated xml translation files.

Development Environment

You should install the dependencies at first

Linux

For Linux developer, you can easily download and install the dependencies and QtCreator from the mirrors. Set the tool kits to qt6 and the compiler we recommend is gcc or the latest clang. Then set up automatic formatting and enable QML debug as mentioned before.

Windows