Manabu Ninja: Contributing to Manabu Ninja

Welcome! We appreciate contributions of all kinds -- bug fixes, new features, vocabulary sets, documentation, and accessibility improvements.

🧰 Prerequisites

Fossil -- Version control. See FOSSIL.md for install instructions
Flutter (>= 3.0) -- App development. Verify with flutter doctor
Task -- Task runner. winget install Task.Task / brew install go-task
Node.js (LTS 18+) -- Only needed for the marketing site or infra
Podman -- Only needed for container images

🛠️ Development Setup

# 1. Clone the repository
fossil clone https://fossil.manabu.ninja manabu-ninja.fossil
mkdir manabu-ninja && cd manabu-ninja
fossil open ../manabu-ninja.fossil

# 2. Install Flutter dependencies
flutter pub get

# 3. Run the app
flutter run

# 4. Verify everything passes
flutter analyze

If you modify the Drift database schema (lib/core/database/database.dart), regenerate code with:

dart run build_runner build

📬 Submitting Changes

Fossil doesn't have pull requests. Here's how to get your changes reviewed and merged:

Post on the Fossil forum (preferred) The project has a built-in forum at fossil.manabu.ninja. Describe what you changed and why, and attach a bundle or patch file (see below).

Email Send your contribution to curtis@klutch.software with a description of the changes.

How to package your changes

If you have commit access, just commit to a named branch -- it will sync automatically.

If you don't have commit access, export your work as a Fossil bundle or a plain diff:

# Option A: Bundle (packages one or more commits)
fossil bundle export --branch my-feature my-feature.bundle

# Option B: Plain diff (for small fixes)
fossil diff > my-fix.patch

Attach the .bundle or .patch file to your forum post or email. See FOSSIL.md for more detail.

📂 Working Across Subprojects

This is a monorepo with three subprojects, each with its own Taskfile:

Directory	What it is	Docs
`lib/`	Flutter app (Dart)	This file
`astro/`	Marketing site (Astro/Node.js)	astro/README.md
`infra/`	Server infrastructure (Pulumi/Podman)	infra/README.md

All task commands run from the project root. Subproject tasks use a module: prefix:

task site:deploy       # Build and deploy marketing site
task infra:status      # Check server container status
task deploy-app        # Deploy Flutter web app (root task)

Run task --list to see everything available.

🏃 Running the App

flutter devices                    # List connected devices and emulators
flutter run -d chrome              # Web (Chrome)
flutter run -d windows             # Windows desktop
flutter run -d emulator-5554       # Android emulator
flutter run -d "Pixel 7"           # Physical Android phone (by name)

Press r during a run to hot reload (applies changes instantly). Press R for a full hot restart.

🏗️ Building for Each Platform

Android

Android Studio (for SDK/emulator) and Java JDK 17+ required. See the Flutter Android guide for emulator setup.

task build-apk                     # Release APK (testing / sideloading)
flutter build appbundle --release  # App Bundle (Play Store, needs android/key.properties)

Windows

Visual Studio 2022 with "Desktop development with C++" workload required. flutter doctor will tell you if this is missing.

task build-windows                 # Release build -> build/windows/x64/runner/Release/

Web

flutter build web --release        # Release build -> build/web/

Note: TTS depends on browser support and may behave differently than on Android/Windows.

🚀 Releasing and Deploying

Release builds are stored as Fossil unversioned files, available at https://fossil.manabu.ninja/uv/.

task release       # Build all platforms + upload to Fossil UV
task deploy-app    # Deploy Flutter web app to server

See FOSSIL.md for UV setup requirements and infra/README.md for server deployment.

🎨 Code Style

Format all Dart code with dart format .
Verify with flutter analyze -- no new warnings or errors before committing
Follow the existing feature-module pattern: models/, screens/, widgets/, controllers/, services/
Use AppLogger (from core/services/logger_service.dart) instead of print()
The project uses flutter_lints -- rules are in analysis_options.yaml

Testing

Testing infrastructure is planned but not yet in place. For now, verify changes with flutter analyze.

Doc comments

Use /// doc comments on public APIs. Start with a capital letter, use a sentence fragment. Skip when the name is self-evident; skip private members.

/// Abstract interface for flashcards used in practice sessions
abstract class PracticeCard {
  /// The Japanese text (hiragana/katakana)
  String get japanese;

  /// Card is complete after 3 consecutive correct answers in a session
  bool get isSessionComplete => correctStreak >= 3;
}

💡 What to Contribute

New vocabulary sets -- Add JSON files under assets/vocab/ and register them in vocabulary_set.dart
Bug fixes -- Check the Fossil issue tracker for open bugs
Accessibility -- Screen reader labels, high-contrast support, keyboard navigation
iOS support -- The iOS target is not currently configured
Documentation -- Improve doc comments, add usage examples, or expand the wiki
Localization -- The UI is currently English-only
New kanji levels -- Add JLPT N3, N2, or N1 kanji groups

🤝 Code of Conduct

We are committed to providing a welcoming and respectful environment for everyone. Please be kind and constructive in all interactions. Harassment or disrespectful behavior will not be tolerated.

📎 Appendix: Task Runner Reference

All commands run from the project root.

Root tasks (Flutter app)

Command	What it does
`task build-apk`	Build Android APK
`task build-windows`	Build Windows executable
`task build`	Build all release artifacts (APK + Windows)
`task deploy-app`	Build Flutter web app and deploy to server
`task release`	Build all platforms + upload to Fossil UV

`infra:` tasks (server ops)

Command	What it does
`task infra:build`	Build container images locally
`task infra:deploy`	Build + push images to server, restart services
`task infra:config`	Push updated Caddyfile to server
`task infra:quadlet`	Push Quadlet files to server
`task infra:ssh`	SSH into server
`task infra:status`	Check server container and systemd status

`site:` tasks (marketing site)

Command	What it does
`task site:build`	Build the Astro site
`task site:deploy`	Build and deploy marketing site to server