Development Guide

This guide covers everything you need to know about contributing to FDAWG, including setting up the development environment, understanding the codebase, and following our development practices.

Prerequisites

Before you start developing FDAWG, ensure you have:

Getting Started

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/fdawg.git
cd fdawg

# Add upstream remote
git remote add upstream https://github.com/Jerinji2016/fdawg.git

2. Install Dependencies

# Install Go dependencies
go mod download

# Install Node.js dependencies for SASS compilation
npm install

3. Build and Test

# Clean and build
make clean
make build

# Test the binary
./build/fdawg --version

4. Development Workflow

# Start development mode (watches SASS files)
make dev

# In another terminal, test your changes
./build/fdawg serve /path/to/test/flutter/project

Project Structure

fdawg/
├── cmd/                    # Application entry points
│   └── flutter-manager/    # Main CLI application
│       └── main.go         # Application entry point
├── internal/               # Private application code
│   ├── commands/           # CLI command implementations
│   │   ├── asset.go        # Asset management commands
│   │   ├── environment.go  # Environment commands
│   │   ├── init.go         # Project validation
│   │   ├── localization.go # Localization commands
│   │   ├── namer.go        # App naming commands
│   │   └── serve.go        # Web server command
│   └── server/             # Web server implementation
│       ├── handlers/       # HTTP request handlers
│       ├── web/            # Web assets and templates
│       │   ├── static/     # Static assets (CSS, JS, images)
│       │   │   ├── css/    # Compiled CSS files
│       │   │   ├── js/     # JavaScript files
│       │   │   └── scss/   # SASS source files
│       │   └── templates/  # HTML templates
│       └── server.go       # Server setup and routing
├── pkg/                    # Reusable packages
│   ├── asset/              # Asset management functionality
│   ├── config/             # Configuration management
│   ├── environment/        # Environment variables management
│   ├── flutter/            # Flutter project utilities
│   ├── localization/       # Localization management
│   ├── namer/              # App name management
│   ├── translate/          # Translation services
│   └── utils/              # Utility functions
├── docs/                   # Documentation (GitHub Pages)
├── dwag_tests/             # Test Flutter project
├── Makefile                # Build automation
├── package.json            # Node.js dependencies
└── go.mod                  # Go module definition

Architecture Overview

Command Structure

FDAWG uses the urfave/cli library for command-line interface:

// cmd/flutter-manager/main.go
app := &cli.App{
    Name:  "fdawg",
    Usage: "Flutter Development Assistant with Go",
    Commands: []*cli.Command{
        commands.ServeCommand,
        commands.InitCommand,
        commands.EnvironmentCommand,
        commands.AssetCommand,
        commands.LocalizationCommand,
        commands.NamerCommand,
        commands.BundlerCommand,
        commands.BuildCommand,
    },
}

Package Organization

pkg/ packages are designed to be reusable and independent:

  • Each package handles a specific domain (assets, environment, etc.)
  • Packages don’t depend on CLI-specific code
  • Can be imported by other Go projects

internal/ packages contain application-specific code:

  • CLI command implementations
  • Web server and handlers
  • Application-specific logic

Web Server Architecture

The web server uses Go’s standard net/http package with:

  • Static file serving for CSS, JS, and images
  • Template rendering for HTML pages
  • JSON API endpoints for dynamic functionality
  • WebSocket support for real-time updates (planned)

Build System Architecture

The build system (pkg/build/) provides comprehensive Flutter build management:

Core Components:

  • BuildManager - Orchestrates the entire build process
  • BuildConfig - YAML-based configuration with validation
  • CommandExecutor - Executes commands with timeout and environment handling
  • Platform implementations - Android, iOS, Web, macOS, Linux, Windows
  • Artifact management - Organized output with naming patterns
  • Setup wizard - Interactive configuration setup

Key Features:

  • Multi-platform builds with platform-specific configurations
  • Pre-build step execution (build_runner, flutter_launcher_icons, etc.)
  • Environment integration using --dart-define-from-file
  • Real-time build output streaming via WebSocket
  • Organized artifact output with date-based folders
  • Parallel build execution (experimental)
  • Dry-run mode for build plan preview

Configuration Structure:

metadata:
  app_name_source: namer    # namer, pubspec, custom
  version_source: pubspec   # pubspec, custom

pre_build:
  global:                   # Run before all platform builds
    - name: "Generate code"
      command: "dart run build_runner build"

platforms:
  android:
    enabled: true
    build_types:
      - name: "release_apk"
        type: "apk"
        build_mode: "release"

artifacts:
  base_output_dir: "build/fdawg-outputs"
  organization:
    by_date: true
    date_format: "January-2"
  naming:
    pattern: "{app_name}_{version}_{arch}"

Development Practices

Code Style

We follow standard Go conventions:

# Format code
go fmt ./...

# Lint code (install golangci-lint first)
golangci-lint run

# Vet code
go vet ./...

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests for specific package
go test ./pkg/asset/...

SASS Development

For web interface styling:

# Compile SASS once
npm run sass

# Watch for changes (development)
npm run sass:watch

# Or use Make
make sass-watch

Building

Development Build

# Clean previous builds
make clean

# Build with SASS compilation
make all

# Or build without SASS
make build

Release Build

# Build optimized binary
make clean
make all

# The binary will be in build/fdawg

Cross-Platform Building

# Build for different platforms
GOOS=linux GOARCH=amd64 go build -o build/fdawg-linux ./cmd/flutter-manager
GOOS=windows GOARCH=amd64 go build -o build/fdawg-windows.exe ./cmd/flutter-manager
GOOS=darwin GOARCH=amd64 go build -o build/fdawg-macos ./cmd/flutter-manager

Testing

Test Flutter Project

Use the included test project for development:

# Navigate to test project
cd dwag_tests

# Test FDAWG commands
../build/fdawg init
../build/fdawg serve
../build/fdawg env list

# Test build system
../build/fdawg build setup --default
../build/fdawg build run --platforms android --dry-run
../build/fdawg build status

Unit Tests

Write tests for new functionality:

// pkg/asset/asset_test.go
func TestAddAsset(t *testing.T) {
    // Test implementation
}

Integration Tests

Test complete workflows:

# Test complete environment workflow
fdawg env create test
fdawg env add TEST_VAR test_value --env test
fdawg env show test
fdawg env delete test

# Test complete build workflow
fdawg build setup --default
fdawg build run --platforms android --dry-run
fdawg build run --platforms web
fdawg build status

Contributing

Workflow

  1. Create a feature branch: 
    git checkout -b feature/your-feature-name
  2. Make your changes:
    • Follow coding standards
    • Add tests for new functionality
    • Update documentation
  3. Test your changes: 
    make clean
make all
go test ./...
  4. Commit your changes: 
    git add .
git commit -m "feat: add new feature description"
  5. Push and create PR: 
    git push origin feature/your-feature-name
# Create pull request on GitHub

Commit Message Format

We use conventional commits:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • style: - Code style changes
  • refactor: - Code refactoring
  • test: - Test additions or changes
  • chore: - Build process or auxiliary tool changes

Pull Request Guidelines

  • Clear description of changes
  • Link to related issues if applicable
  • Include tests for new functionality
  • Update documentation as needed
  • Ensure CI passes before requesting review

Adding New Features

Adding a New Command

  1. Create command file: 
    // internal/commands/newcommand.go
package commands
   
import "github.com/urfave/cli/v2"
   
var NewCommand = &cli.Command{
    Name:  "newcommand",
    Usage: "Description of new command",
    Action: func(c *cli.Context) error {
        // Implementation
        return nil
    },
}
  2. Add to main.go: 
    // cmd/flutter-manager/main.go
Commands: []*cli.Command{
    // ... existing commands
    commands.NewCommand,
},
  3. Create package if needed: 
    // pkg/newfeature/newfeature.go
package newfeature
   
// Implementation

Adding Web Interface Features

  1. Create HTML template: 
    <!-- internal/server/web/templates/newfeature.html -->
{{define "content"}}
<div class="project-info">
    <!-- Your HTML content -->
</div>
{{end}}
  2. Add route handler: 
    // internal/server/handlers/newfeature.go
func NewFeatureHandler(w http.ResponseWriter, r *http.Request) {
    // Handler implementation
}
  3. Add JavaScript if needed: 
    // internal/server/web/static/js/newfeature.js
// JavaScript functionality
  4. Update navigation: 
    <!-- internal/server/web/templates/layout.html -->
<li>
    <a href="/newfeature">
        <i class="fas fa-icon"></i>
        <span>New Feature</span>
    </a>
</li>

Debugging

Debug Mode

# Enable verbose logging
export FDAWG_DEBUG=true
./build/fdawg serve

# Or use Go's built-in debugging
go run -race ./cmd/flutter-manager serve

Common Issues

Build failures:

  • Check Go version compatibility
  • Ensure all dependencies are installed
  • Run go mod tidy

SASS compilation issues:

  • Check Node.js version
  • Run npm install
  • Verify SASS files syntax

Test failures:

  • Ensure test Flutter project is valid
  • Check file permissions
  • Verify Go module dependencies

Release Process

Version Management

  1. Update version in relevant files
  2. Create git tag: 
    git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
  3. Build release binaries: 
    make clean
make all
# Build for multiple platforms
  4. Create GitHub release with binaries

Documentation Updates

  • Update README.md if needed
  • Update documentation in docs/
  • Ensure GitHub Pages builds correctly

Getting Help

Resources

Development Questions

When asking for help:

  1. Describe what you’re trying to achieve
  2. Include relevant code snippets
  3. Provide error messages if any
  4. Mention your development environment

Thank you for contributing to FDAWG! Your contributions help make Flutter development more efficient for everyone.