Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
387 lines (284 loc) · 10.2 KB

CONTRIBUTING.md

File metadata and controls

387 lines (284 loc) · 10.2 KB
Raw

Contributing to GOverlay

Thank you for your interest in contributing to GOverlay! 🎉

This document provides guidelines for contributing to the project. Following these guidelines helps maintain code quality and makes the review process smoother for everyone.

Table of Contents

Code of Conduct

Be respectful and considerate of others. This is a community project, and we value contributions from everyone. Harassment, discrimination, or any form of abusive behavior will not be tolerated.

Getting Started

Prerequisites

Before you start contributing, ensure you have the following tools installed:

Required Tools

Runtime Dependencies

Setting Up Development Environment

  1. Fork and clone the repository:

    git clone https://github.com/YOUR_USERNAME/goverlay.git
cd goverlay

  2. Open the project in Lazarus IDE:

    lazarus-ide goverlay.lpi

    Or simply open goverlay.lpi from the IDE.

  3. Build the project:

    make

  4. Run the application:

    ./start_goverlay.sh

How to Contribute

Reporting Bugs

If you find a bug, please create an issue on GitHub Issues with the following information:

  • Clear title describing the issue
  • Description of what happened vs. what you expected
  • Steps to reproduce the bug
  • Environment details:
    • GOverlay version
    • Distribution and version
    • Installation method (Flatpak, native, AppImage, etc.)
    • MangoHud/vkBasalt/OptiScaler versions
  • Logs or screenshots if applicable

Example:

### Bug: vkBasalt toggle key not saving

**Expected:** Selected toggle key should be saved to config
**Actual:** Always saves "Home" regardless of selection

**Steps to Reproduce:**
1. Open GOverlay
2. Go to vkBasalt tab
3. Select "F1" from toggle key dropdown
4. Click Save
5. Check vkBasalt config - shows "Home"

**Environment:**
- GOverlay 1.7.0 (Flatpak)
- Arch Linux
- vkBasalt 0.3.2

Suggesting Features

Feature requests are welcome! Please create an issue with:

  • Clear description of the feature
  • Use case - why is this useful?
  • Proposed implementation (optional)
  • Mockups or examples (if applicable)

Submitting Pull Requests

  1. Create a new branch for your changes:

    git checkout -b feature/your-feature-name

    or

    git checkout -b fix/bug-description

  2. Make your changes following the Development Guidelines

  3. Test your changes thoroughly:

    • Build and run the application
    • Test affected functionality
    • Run validation tests: make tests

  4. Commit your changes with clear, descriptive messages

  5. Push to your fork:

    git push origin feature/your-feature-name

  6. Open a Pull Request on GitHub with:

    • Clear title describing the change
    • Description of what was changed and why
    • Reference to related issues (e.g., "Fixes #123")
    • Screenshots/recordings for UI changes
    • Testing performed

Development Guidelines

Code Style

GOverlay is written in Object Pascal using the Lazarus IDE. Follow these guidelines:

General Rules

  • Use meaningful variable and function names
  • Keep functions focused and concise (single responsibility)
  • Add comments for complex logic
  • Use consistent indentation (2 spaces recommended)
  • Place opening braces on the same line (K&R style)

Naming Conventions

  • Units/Files: lowercase or descriptivename.pas
  • Classes: TPascalCase (e.g., TThemeManager)
  • Functions/Procedures: PascalCase (e.g., SaveConfiguration)
  • Variables: camelCase (e.g., configPath, isEnabled)
  • Constants: UPPER_CASE or PascalCase (e.g., MAX_SIZE, DefaultPath)
  • UI Components: descriptive names with type suffix (e.g., saveButton, configEdit, mangoCheckbox)

Example Code

procedure TSomeUnit.LoadConfiguration;
var
  configFile: TStringList;
  configPath: string;
  i: Integer;
begin
  configPath := GetConfigPath;
  
  if not FileExists(configPath) then
  begin
    ShowMessage('Configuration file not found');
    Exit;
  end;

  configFile := TStringList.Create;
  try
    configFile.LoadFromFile(configPath);
    
    for i := 0 to configFile.Count - 1 do
    begin
      // Process configuration lines
      ProcessConfigLine(configFile[i]);
    end;
  finally
    configFile.Free;
  end;
end;

Commit Messages

Write clear, descriptive commit messages following this format:

<type>: <short description>

<optional longer description>

<optional footer with issue references>

Types:

  • feat: - New feature
  • fix: - Bug fix
  • refactor: - Code refactoring (no functional change)
  • docs: - Documentation changes
  • style: - Code style/formatting changes
  • test: - Adding or updating tests
  • chore: - Build process, dependencies, etc.

Examples:

feat: add display_server option to MangoHud config

Added checkbox to enable/disable display_server in MangoHud configuration.
This allows users to show the current display server in the overlay.

Fixes #245
fix: vkBasalt toggle key always saving as Home

Fixed bug where selected toggle key from dropdown was not being saved.
Now correctly writes the selected key (F1-F4, Home) to vkBasalt config.

Fixes #312

Testing

Before submitting a PR, ensure:

  1. The project compiles without errors:

    make clean
make

  2. Run validation tests:

    make tests

    This validates the .desktop and .metainfo.xml files.

  3. Manual testing:

    • Test the specific feature/fix you implemented
    • Test on both native and Flatpak environments (if applicable)
    • Verify UI changes work correctly with both light and dark themes
    • Check that configuration files are saved and loaded correctly

  4. Test different scenarios:

    • Fresh install (no existing config)
    • Existing config (ensure backwards compatibility)
    • Edge cases (empty values, invalid inputs, etc.)

Project Structure

goverlay/
├── data/                     # Application data files
│   ├── icons/               # Application icons
│   ├── fgmod/               # FGMOD scripts and resources
│   ├── *.desktop            # Desktop entry file
│   └── *.metainfo.xml       # AppStream metadata
├── *.pas                    # Pascal source files
│   ├── overlayunit.pas      # Main MangoHud/vkBasalt/OptiScaler UI
│   ├── themeunit.pas        # Theme management
│   ├── optiscaler_update.pas # OptiScaler update logic
│   ├── configmanager.pas    # Configuration handling
│   ├── systemdetector.pas   # System detection utilities
│   └── ...                  # Other units
├── *.lfm                    # Lazarus form files (UI layouts)
├── goverlay.lpi             # Lazarus project file
├── goverlay.lpr             # Main program file
├── Makefile                 # Build configuration
├── README.md                # Project documentation
├── LICENSE                  # GPL-3.0 license
└── CONTRIBUTING.md          # This file

Key Files

  • overlayunit.pas - Main application logic and UI
  • themeunit.pas - Dark/light theme management
  • configmanager.pas - Configuration file handling
  • optiscaler_update.pas - OptiScaler download and update logic
  • fgmod_resources.pas - Embedded FGMOD scripts
  • Makefile - Build automation

Building and Running

Standard Build

# Build the project
make

# Run locally
./start_goverlay.sh

# Install system-wide
sudo make install

# Uninstall
sudo make uninstall

Flatpak Build

# Build Flatpak locally
./flatpak/build-flatpak.sh

# Install the local build
flatpak install --user flatpak-repo io.github.benjamimgois.goverlay

Clean Build

# Clean build artifacts
make clean

Additional Resources

License

By contributing to GOverlay, you agree that your contributions will be licensed under the GNU General Public License v3.0.

See LICENSE for the full license text.

Questions?

If you have questions about contributing, feel free to:

Thank you for contributing to GOverlay! Your efforts help make Linux gaming better for everyone. 🚀