diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..852315f1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing to Spark Client + +Thank you for your interest in contributing to Spark! + +## How to Contribute + +1. **Keep changes scoped** to the feature you are editing +2. **Run format, codegen (if needed), and analyze** before opening a PR +3. **Test on a real device or simulator** and add screenshots when applicable. + +## Development + +### Prerequisites + +- Flutter SDK 3.41+ +- Dart SDK matching Flutter toolchain +- Xcode (for iOS builds) and/or Android SDK + +### Setup + +From repository root: + +```bash +touch .env +flutter pub get --enforce-lockfile # install dependencies +dart run build_runner build --delete-conflicting-outputs # generated code +flutter run +``` + +### Before Submitting + +1. Format your code: + ```bash + dart format . + ``` + +2. Analyze for issues: + ```bash + flutter analyze . + ``` + +3. If you changed annotations/models, regenerate code: + ```bash + dart run build_runner build --delete-conflicting-outputs + ``` + +### Pull Request Guidelines + +1. Make your changes following the codebase conventions +2. Ensure CI passes (format check, analyze, build) +4. Use conventional commit titles. e.g. "fix: remove misshapen meatballs" or + "feat(fruit): add strawberries" + +## Code Conventions + +- Prefer `package:spark/...` imports; avoid deep relative imports +- Import order: Dart SDK, third-party, project; keep `part` after imports +- Use strong explicit types; avoid `dynamic` +- Use Freezed for immutable models and `@riverpod` for providers +- Naming: types `PascalCase`, members/providers `lowerCamelCase`, private + `_name` +- Keep feature flow: external/API/storage -> repository -> provider -> widget diff --git a/README.md b/README.md index 5964cca1..38591e46 100644 --- a/README.md +++ b/README.md @@ -1,89 +1,32 @@ -# Spark Client +# Spark Social App -Flutter client for Spark social. This repository contains the production mobile app, -plus workspace packages used by the app (assets, fonts, and widgetbook). +Welcome to the codebase for the Spark Social mobile app. -## What This Repo Contains +Get the Spark Social app: -- `spark` app package at repo root (`pubspec.yaml`) -- Flutter workspace members: - - `widgetbook` (component/dev preview package) - - `fonts` (shared font package) - - `assets` (shared assets package) +- iOS +- Android -The app is organized with a feature-first structure and uses Riverpod + GetIt + -Freezed + AutoRoute. - -## Tech Stack - -- Flutter / Dart -- Riverpod (with code generation) -- GetIt for dependency injection -- Freezed + json_serializable for immutable models -- AutoRoute for navigation -- AT Protocol client libraries (`atproto`, `bluesky`) - -## Prerequisites - -- Flutter SDK (CI uses stable `3.41.3`) -- Dart SDK matching Flutter toolchain -- Xcode (for iOS builds) and/or Android SDK - -## Quick Start - -From repository root: - -```bash -touch .env -flutter pub get --enforce-lockfile -dart run build_runner build --delete-conflicting-outputs -flutter run -``` - -## Common Commands - -### Dependencies and codegen - -```bash -flutter pub get --enforce-lockfile -dart run build_runner build --delete-conflicting-outputs -dart run build_runner watch --delete-conflicting-outputs -``` - -### Lint and format - -```bash -flutter analyze lib -flutter analyze . -dart format . -dart format --set-exit-if-changed . -``` - -### Tests - -No tests are currently committed, but these are the standard commands: +## Overview -```bash -flutter test -flutter test test/path/to/some_test.dart -flutter test test/path/to/some_test.dart --plain-name "does something specific" -``` +This repo contains the mobile client for Spark Social. This is a Flutter app, +written in Dart, using MaterialApp as its base. -For `widgetbook` (run inside `widgetbook/`): +Spark is an open source shortform social app for photos and videos built on AT +Protocol. It's an open alternative to closed platforms like Instagram and +Tiktok. -```bash -flutter test -``` +We support stories, reusable sounds, DMs, and we have a built-in photo and video +editor powered by [pro_image_editor](https://github.com/hm21/pro_image_editor). -### Builds +## Structure -```bash -flutter build appbundle -flutter build apk -flutter build ios --no-codesign -``` +The app is organized with a feature-first structure and uses Riverpod + GetIt + +Freezed + AutoRoute. We also utilize the open source +[atproto.dart](https://github.com/myConsciousness/atproto.dart) client +libraries. -## Project Layout +### Project Layout ```text lib/ @@ -100,29 +43,24 @@ fonts/ # local font package assets/ # local assets package ``` -## Architecture Notes - -- Prefer package imports (`package:spark/...`) for app code. -- Typical flow is: external/API/storage -> repository -> provider -> widget. -- Providers are generated with `@riverpod`; immutable state is typically Freezed. -- Generated files (`*.g.dart`, `*.freezed.dart`, `*.gr.dart`) should not be edited manually. - -## CI Overview +## Resources -- Lint workflow runs codegen, then `flutter analyze`. -- Android internal release workflow runs codegen, config setup, then `flutter build appbundle`. +Spark Social is built on [AT Protocol](https://atproto.com/), a protocol for +decentralized social networks. This allows for unprecidented amounts of +user-autonomy and data ownership, and ensures no one entity is in charge of the +network. -See: +The lexicon schemas for the records published and APIs used by this app are +under the `so.sprk.*` namespace. -- `.github/workflows/flutter_lint.yml` -- `.github/workflows/android-internal-release.yml` +The API server or "AppView" this app uses can be found in the +[server repo](https://github.com/sprksocial/server), and contains the +`sprk.so.*` lexicon schemas used in this client. ## Contributing -1. Keep changes scoped to the feature you are editing. -2. Run format, codegen (if needed), and analyze before opening a PR. -3. Do not commit secrets (`.env`, signing keys, service credentials). +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License -MIT. See `LICENSE`. +MIT Licensed. See [LICENSE](LICENSE).