Skip to content
Wails Blog

Getting Started

Welcome, Contributor!

Section titled “Welcome, Contributor!”

Thank you for your interest in contributing to Wails! This guide will help you make your first contribution.

Prerequisites

Section titled “Prerequisites”

Before you begin, ensure you have:

  • Go 1.25+ installed (download)
  • Node.js 20+ and npm (download)
  • Git configured with your GitHub account
  • Basic familiarity with Go and JavaScript/TypeScript

Platform-Specific Requirements

Section titled “Platform-Specific Requirements”

macOS:

  • Xcode Command Line Tools: xcode-select --install

Windows:

  • MSYS2 or similar Unix-like environment recommended
  • WebView2 runtime (usually pre-installed on Windows 11)

Linux:

  • gcc, pkg-config, libgtk-3-dev, libwebkit2gtk-4.0-dev
  • Install via: sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.0-dev (Debian/Ubuntu)

Contribution Process Overview

Section titled “Contribution Process Overview”

The typical contribution workflow follows these steps:

  1. Fork & Clone - Create your own copy of the Wails repository
  2. Setup - Build the Wails CLI and verify your environment
  3. Branch - Create a feature branch for your changes
  4. Develop - Make your changes following our coding standards
  5. Test - Run tests to ensure everything works
  6. Commit - Commit with clear, conventional commit messages
  7. Submit - Open a pull request for review
  8. Iterate - Respond to feedback and make adjustments
  9. Merge - Once approved, your changes become part of Wails!

Step-by-Step Guide

Section titled “Step-by-Step Guide”

Choose your contribution type:

  1. Find or Report the Bug

    • Check if the bug is already reported in GitHub Issues
    • If not, create a new issue with steps to reproduce
    • Wait for confirmation before starting work

  2. Fork and Clone

    Fork the repository at github.com/wailsapp/wails/fork

    Clone your fork:

    Terminal window
    git clone https://github.com/YOUR_USERNAME/wails.git
    cd wails
    git remote add upstream https://github.com/wailsapp/wails.git

  3. Build and Verify

    Build Wails and verify you can reproduce the bug:

    Terminal window
    cd v3
    go build -o ../wails3 ./cmd/wails3
    

    # Reproduce the bug to understand it

  4. Create a Bug Fix Branch

    Create a branch for your fix:

    Terminal window
    git checkout -b fix/issue-123-window-crash

  5. Fix the Bug

    • Make the minimal changes needed to fix the bug
    • Don’t refactor unrelated code
    • Add or update tests to prevent regression
    Terminal window
    # Make your changes
    # Add tests in *_test.go files

  6. Test Your Fix

    Run tests to ensure the fix works:

    Terminal window
    go test ./...
    

    # Test the specific package
    go test ./pkg/application -v
    

    # Run with race detector
    go test ./... -race

  7. Commit Your Fix

    Commit with a clear message:

    Terminal window
    git commit -m "fix: prevent window crash when closing during initialization
    

    Fixes #123"

  8. Submit Pull Request

    Push and create PR:

    Terminal window
    git push origin fix/issue-123-window-crash

    In your PR description:

    • Explain the bug and root cause
    • Describe your fix
    • Reference the issue: “Fixes #123”
    • Include before/after behavior

  9. Respond to Feedback

    Address review comments and update your PR as needed.

Finding Issues to Work On

Section titled “Finding Issues to Work On”

Getting Help

Section titled “Getting Help”

Code of Conduct

Section titled “Code of Conduct”

Be respectful, constructive, and welcoming. We’re building a friendly community focused on creating great software together.

Next Steps

Section titled “Next Steps”