How to Contribute

Fork the Repository

Go to the SQLvanta GitHub page and click Fork to create a copy under your own account. This gives you full write access to experiment without touching the main repo.

# After forking, clone your fork
git clone https://github.com/YOUR_USERNAME/sqlvanta.git
cd sqlvanta

# Add the original repo as "upstream" so you can pull future changes
git remote add upstream https://github.com/senthilnasa/sqlvanta.git

Set Up Your Development Environment

SQLvanta requires Flutter 3.x (stable channel) with desktop support enabled. Run the commands below to get everything ready.

# Verify Flutter is on stable channel with desktop enabled
flutter channel stable
flutter upgrade
flutter config --enable-windows-desktop  # or --enable-macos-desktop / --enable-linux-desktop
flutter doctor

# Install dependencies
flutter pub get

# Generate Drift DB, Riverpod providers, and Freezed models
dart run build_runner build --delete-conflicting-outputs

# Run on your platform
flutter run -d windows   # or -d macos / -d linux

Create a Feature Branch

Always branch off main. Use a descriptive name that summarises what you're adding or fixing.

# Pull the latest upstream changes first
git fetch upstream
git checkout main
git merge upstream/main

# Create your feature branch
git checkout -b feature/csv-export
# Examples: feature/ssh-tunneling  fix/connection-timeout  docs/contributing-guide

Follow the Clean Architecture Structure

SQLvanta uses a strict three-layer architecture per feature module. Every new feature lives under lib/features/<name>/ with the following structure:

Naming rules to follow:

# Files       → snake_case
connection_entity.dart

# Classes     → PascalCase
ConnectionEntity, SaveConnection, ConnectionModel

# Providers   → camelCase + Provider suffix
connectionListProvider

# Use cases   → VerbNoun
GetAllConnections, SaveConnection, DeleteConnection

# Riverpod notifier class (codegen)
class ConnectionList extends _$ConnectionList { ... }

Add a Route (if adding a new screen)

New screens must be registered in lib/app/router.dart. Follow the existing GoRoute pattern.

# lib/app/router.dart — add inside the routes list
GoRoute(
  path: '/my-feature',
  builder: (context, state) => const MyFeatureScreen(),
),

Test Your Changes

Run unit and widget tests, then manually verify your feature builds and works on at least one desktop platform.

flutter test                      # unit + widget tests
flutter test integration_test/     # integration tests (optional)
flutter analyze                    # static analysis — must pass with zero errors

Commit and Push

Write clear, focused commit messages. Squash work-in-progress commits before pushing if you prefer a clean history.

git add lib/features/my_feature/
git commit -m "feat: add CSV export to results grid"
git push origin feature/csv-export

Open a Pull Request

Go to your fork on GitHub. You'll see a prompt to Compare & pull request. Target the main branch of senthilnasa/sqlvanta.

PR title format suggestions:

feat: add SSH tunnel support to connection manager
fix: resolve timeout when querying large result sets
docs: improve keyboard shortcuts section in README
refactor: split workspace_provider into smaller notifiers

Before submitting, run through this checklist:

• Feature builds and runs on Windows, macOS, or Linux
• flutter analyze reports zero errors
• flutter test passes with no failures
• New code follows the clean architecture layer rules
• No passwords, API keys, or secrets committed
• If Drift/Riverpod/Freezed files changed, build_runner was re-run and *.g.dart files are included in the commit
• PR targets the main branch of the upstream repo