Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (96 loc) · 4.38 KB

CONTRIBUTING.md

File metadata and controls

134 lines (96 loc) · 4.38 KB

Contributing to flompt

Thanks for wanting to contribute! flompt is open-source and MIT licensed — PRs, bug reports, and feature ideas are all welcome.

Table of Contents

Getting started

Requirements: Node.js 18+, Python 3.12+

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/flompt.git
cd flompt

# 2. Start the backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env    # optional: add your Anthropic/OpenAI key
uvicorn app.main:app --reload --port 8000

# 3. Start the frontend (new terminal)
cd app
npm install
npm run dev             # → http://localhost:5173

The heuristic decomposer works without an API key — you don't need one to develop most features.

Project structure

flompt/
├── app/          # React 18 + Vite frontend (TypeScript)
│   └── src/
│       ├── components/   # UI components
│       ├── i18n/         # 10 locale JSON files
│       ├── lib/          # assemblePrompt, analytics, platform
│       ├── services/     # HTTP client (axios)
│       ├── store/        # Zustand state
│       └── types/        # TypeScript types (blocks.ts)
├── backend/      # FastAPI backend (Python)
│   └── app/
│       ├── routers/      # decompose, compile
│       └── services/     # ai_service, compiler, decomposer
├── blog/         # Next.js blog (static export)
├── extension/    # Chrome / Firefox / Safari MV3 extension
├── docs/         # GitBook documentation
└── landing/      # Static landing page

For a deeper dive, read CLAUDE.md — it covers design rules, block ordering, CSS conventions, and deployment architecture.

Development workflow

  1. Create a branch from master:

    git checkout -b feat/my-feature

  2. Make your changes — keep commits focused and atomic.

  3. Test locally before opening a PR:

    • Frontend: npm run build in app/ should succeed with no errors
    • Backend: your new route/service should handle edge cases gracefully
    • If you touched the extension: test on at least one browser

  4. Open a PR — the template will guide you.

Code style

  • TypeScript everywhere in the frontend. New types go in app/src/types/blocks.ts.
  • No inline styles — use CSS classes. New design tokens go in :root in app/src/styles.css.
  • No console.log in production code paths.
  • English only in source code (comments, variable names, function names). UI strings live in i18n JSON files.
  • Backend: we use Ruff for linting. Run ruff check app/ before committing.

Adding a block type

Block types are defined in two places:

  1. app/src/types/blocks.ts — add the new type literal to BlockType
  2. app/src/lib/assemblePrompt.ts — add it to TYPE_PRIORITY (controls XML ordering) and XML_TAG_MAP (controls the output XML tag)
  3. backend/app/services/compiler.py — add the XML tag mapping
  4. backend/app/services/decomposer.py — add keyword heuristics for auto-detection
  5. All 10 i18n files in app/src/i18n/ — add blockType.<newType> label and description

Read docs/block-types.md to understand the existing block taxonomy before adding a new one.

Adding a language

  1. Copy app/src/i18n/en.json to app/src/i18n/<locale>.json
  2. Translate all string values (keep keys in English)
  3. Add the locale to SUPPORTED_LOCALES in app/src/i18n/LocaleContext.tsx
  4. Add a blog translation folder: blog/content/posts/<locale>/
  5. Add the locale to blog/src/i18n/config.ts

Submitting a PR

  • Target the master branch
  • Keep PRs focused — one feature or fix per PR
  • The CI will run lint + build checks automatically
  • A maintainer will review and merge

If you're working on something large, open an issue first to discuss the approach before investing a lot of time.

Questions?

Open a GitHub Discussion or drop a message in an issue. We're friendly.