Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CONTRIBUTING_RU.md
• conventions.md
• CHANGELOG.md
• tasklist.md
• idea.md
• README.md
• README_RU.md
• packaging/README.md
• sofl/preferences.py
• packaging/flatpak/org.badkiko.sofl.yml
• sofl/details_dialog.py
• packaging/arch/build.sh
• sofl/preferences/import_sources.py
• scripts/dev.sh
• sofl/main.py
• scripts/build_all.sh
• sofl/preferences_backup.py

This guide provides all the necessary information for developers wishing to contribute to the Steam Online Fix Launcher (SOFL) project. It covers everything from setting up the development environment to submitting code, adhering to project conventions, and understanding the architecture. The goal of SOFL is to create an easy-to-use launcher that simplifies running multiplayer games on Linux by automatically configuring the environment.

Contributing to SOFL helps make Linux a better platform for gamers. We welcome contributions for fixing bugs, adding features, improving documentation, and helping with translations.

Sources: CONTRIBUTING.md:3, idea.md:5-15, README.md:83-85

1. Getting Started

To begin contributing, you need to set up a local development environment. This involves forking the repository, cloning it, creating a feature branch, and running the application in development mode.

Sources: CONTRIBUTING.md:12-23

The following diagram illustrates the quick start process.

Quick Start Commands

Follow these steps in your terminal to get your environment ready:

1. Fork and Clone:

   # 1. Fork the repository on GitHub
   # 2. Clone your fork
   git clone https://github.com/YOUR_USERNAME/steam-online-fix-launcher.git
   cd steam-online-fix-launcher
   

2. Create a Branch:

   # 3. Create a working branch
   git checkout -b my-feature
   

3. Run for Development:
   The project includes a development script that handles setup, building, and running the application with the correct environment variables.

   # 4. Run the application for development
   ./scripts/dev.sh
   

   This script is the recommended way to run the application during development. It automatically handles building and installing dependencies into a local .local directory.

Sources: CONTRIBUTING.md:14-23, scripts/dev.sh:6-9

2. Development Workflow

Creating a Pull Request

The standard workflow for contributing code is through GitHub Pull Requests.

The diagram below shows the sequence of actions for submitting a change.

Steps:

1. Make changes in your local codebase.
2. Test your changes to ensure everything works as expected by running ./scripts/dev.sh.
3. Commit your changes with a clear, descriptive message following the project's commit conventions.

   git add .
   git commit -m "Brief description of changes"
   

4. Push the changes to your forked repository on GitHub.

   git push origin my-feature
   

5. Create a Pull Request on the official SOFL GitHub repository, providing a brief description of the new feature or fix.

Sources: CONTRIBUTING.md:29-41

Bug Reports and Feature Requests

• Report a Bug: Use GitHub Issues with the provided template. Include what you were doing, what you expected, what happened, and your system details (Linux distribution, version).
• Suggest a Feature: Create an Issue describing what the feature will do, why it's useful, and how it should work.

Sources: CONTRIBUTING.md:47-62

3. Project Architecture and Conventions

To maintain code quality and consistency, SOFL adheres to specific architectural principles and coding conventions.

Sources: conventions.md

3.1. Core Principles

The project is guided by the following principles:

Principle	Description
KISS	Keep solutions simple and avoid over-engineering.
DRY	Avoid duplicating code; refactor into reusable components.
SOLID	Write readable, maintainable, and scalable code.
Modularity	Design independent, self-contained components.
GTK4-first	Prioritize native GTK4 and LibAdwaita widgets.
Async-ready	Use asynchronous operations to ensure a responsive UI.

Sources: conventions.md:6-14

3.2. Project Structure

The project follows a modular structure to separate concerns.

The diagram below outlines the main directories and their purpose.

3.3. Code Style

• Python:
  • Formatting: We use Black with a maximum line length of 88 characters.
  • Style Guide: Follow PEP 8 with 4-space indentation.
  • Typing: Use Type hints for all function signatures and variables to improve readability and allow for static analysis.
  • Encoding: All files must use UTF-8 encoding.
• GTK/Interface:
  • Guidelines: Follow the GNOME Human Interface Guidelines (HIG).
  • Components: Prioritize using LibAdwaita components over older GTK widgets.
  • Responsiveness: Design adaptive UIs without fixed widget sizes.

Sources: CONTRIBUTING.md:101-105, conventions.md:16-24

3.4. Commit Messages

Commit messages must follow a specific format using tags to indicate the nature of the changes.

Format:

[AMR] Brief description of changes

Detailed description if needed.

Tag	Meaning	Description
A	Added	For adding new files or features.
M	Modified	For changing existing files.
R	Removed	For deleting files or features.

You can combine tags, for example, [AM] if you added a new file and modified an existing one in the same commit.

Examples:

• [A] added file new_feature.py
• [M] changed file README.md
• [R] removed file old_script.py

Sources: CONTRIBUTING.md:109-117, conventions.md:61-69

4. Technical Environment

4.1. System Requirements

The following are the minimum requirements for developing and building SOFL:

• Python 3.10+
• GTK4 4.14+ & LibAdwaita 1.4+
• Meson build system
• blueprint-compiler for compiling .blp UI files.

Sources: CONTRIBUTING.md:81-84, conventions.md:26-30, packaging/flatpak/org.badkiko.sofl.yml:30-34

4.2. Development Scripts

The scripts/ directory contains helpers for development and packaging. The most important one is dev.sh.

The dev.sh script automates the local development cycle.

Command	Description
setup	Configures Meson in builddir with a local prefix (.local).
build	Compiles the project using Meson.
install	Installs the application into the local .local prefix.
run	Runs the application with the correct environment variables.
smart	Automatically checks if setup, build, or install are needed and runs them before launching the app. This is the recommended command.
rebuild-run	Cleans the builddir and performs a full setup, build, install, and run cycle.
shell	Starts an interactive shell with the development environment variables set.
clean	Removes the builddir and .local directories.
deps	Creates a .venv and installs Python runtime dependencies.

Sources: scripts/dev.sh:10-33

5. Translations

Contributions to translations are highly welcome.

Translation Workflow

The process for adding or updating translations is managed via standard gettext tools and Meson.

Adding a New Language

1. Add the two-letter language code to po/LINGUAS.

   echo "ru" >> po/LINGUAS
   

2. Create the .po file for your language.

   msginit --input=po/sofl.pot --locale=ru --output=po/ru.po
   

3. Translate the strings in the newly created .po file using a text editor or a specialized tool like Poedit.
4. Submit your changes as a Pull Request.

Sources: CONTRIBUTING.md:90-95

Updating Translations

To update existing translation files after source code changes:

1. First, update the template .pot file.
2. Then, merge the changes into all language-specific .po files.

meson compile sofl-pot -C builddir
meson compile sofl-update-po -C builddir

Sources: CONTRIBUTING.md:97-99

6. Packaging

The project supports packaging for Flatpak, Debian, and Arch Linux. The relevant files and scripts are located in the packaging/ directory. The scripts/build_all.sh script can be used to build all package types.

Sources: packaging/README.md:5-9, scripts/build_all.sh

This diagram shows the general flow of the packaging process.

---

Thank you for your interest in contributing to SOFL! Your efforts help make the Linux gaming ecosystem stronger.

Sources: CONTRIBUTING.md:119-121