From 15d69f0ad6e0008e6472a6b437f9b3e3b83902ef Mon Sep 17 00:00:00 2001 From: mackeh Date: Sat, 14 Feb 2026 10:48:20 +0100 Subject: [PATCH] docs(onboarding): add 10-minute tutorial and contributor templates --- CHANGELOG.md | 2 + README.md | 10 +- docs/CONTRIBUTING.md | 192 ++++++++---------- docs/ONBOARDING.md | 91 +++++---- docs/README.md | 3 + .../workflows/first-automation.workflow.json | 62 ++++++ docs/templates/activity-proposal.md | 50 +++++ docs/templates/demo-script-template.md | 34 ++++ .../node-implementation-checklist.md | 35 ++++ docs/tutorials/FIRST_AUTOMATION_10_MIN.md | 67 ++++++ 10 files changed, 392 insertions(+), 154 deletions(-) create mode 100644 docs/examples/workflows/first-automation.workflow.json create mode 100644 docs/templates/activity-proposal.md create mode 100644 docs/templates/demo-script-template.md create mode 100644 docs/templates/node-implementation-checklist.md create mode 100644 docs/tutorials/FIRST_AUTOMATION_10_MIN.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 24e1cc9..f280ebf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,12 +15,14 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht - Web recorder stop endpoint (`/api/recorders/web/stop`) and recorder navigation event capture. - Recorder draft review panel with reorder/edit/skip controls before inserting recorded steps. - Autopilot plan diagnostics: overall confidence score, node-level insights, and fallback template options. +- Contributor onboarding package: 10-minute tutorial, starter workflow file, and reusable docs templates. ### Changed - CI now includes browser smoke validation (`Web E2E Smoke`). - Web editor keyboard shortcuts now include undo/redo and selection-aware delete behavior. - Web recorder now follows capture -> review -> insert flow instead of immediate node injection. - Autopilot now requires explicit confirm-before-create flow and uses richer starter templates for vague prompts. +- Onboarding/contributing docs now use change-type contribution paths and an explicit definition-of-done checklist. ## [1.0.7] - 2026-02-13 diff --git a/README.md b/README.md index 00f056e..d21266e 100644 --- a/README.md +++ b/README.md @@ -57,9 +57,10 @@ Use these guided demos to evaluate the platform quickly: ## Contributor Onboarding New contributors should start here: -1. `docs/ONBOARDING.md` (30-minute setup + first contribution path) -2. `docs/CONTRIBUTING.md` (standards, testing, QA checklist) -3. `.github/pull_request_template.md` (PR structure used in this repo) +1. `docs/tutorials/FIRST_AUTOMATION_10_MIN.md` (fast baseline walkthrough) +2. `docs/ONBOARDING.md` (setup + contribution tracks) +3. `docs/CONTRIBUTING.md` (standards, definition of done, PR workflow) +4. `.github/pull_request_template.md` (PR structure used in this repo) Good first areas: - UI polish and node inspector UX (`apps/web/src`) @@ -127,10 +128,13 @@ Tag pushes (`v*.*.*`) trigger `.github/workflows/release.yml`, which reruns vali - `docs/README.md` - `docs/DEMOS.md` - `docs/ONBOARDING.md` +- `docs/tutorials/FIRST_AUTOMATION_10_MIN.md` +- `docs/examples/workflows/first-automation.workflow.json` - `docs/ARCHITECTURE.md` - `docs/API_REFERENCE.md` - `docs/DEPLOYMENT.md` - `docs/CONTRIBUTING.md` +- `docs/templates/*` - `AGENTS.md` (repository contributor guide) - `CHANGELOG.md` - `CODE_OF_CONDUCT.md` diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index f7cdb3b..cda5792 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,31 +1,27 @@ # Contributing to ForgeFlow -This guide standardizes local setup, coding practices, and contribution workflow. +This guide standardizes setup, engineering quality, and PR delivery. -Start here if you are new: -- `docs/ONBOARDING.md` for the fastest first-PR path. -- `docs/DEMOS.md` for repeatable product walkthrough flows. -- `CODE_OF_CONDUCT.md` for expected behavior in community interactions. +Start here if new: +- `docs/ONBOARDING.md` +- `docs/tutorials/FIRST_AUTOMATION_10_MIN.md` +- `CODE_OF_CONDUCT.md` ## 1. Prerequisites - - Docker + Docker Compose -- Node.js 20+ (for local non-container development) -- Python 3.11+ (for local agent work) -- Linux desktop/X11 setup if working on desktop automation flows +- Node.js 20+ +- Python 3.11+ (for `apps/agent` work) ## 2. Development Setup -## Option A: Recommended (Docker) - +Recommended: ```bash ./start.sh ``` -## Option B: App-by-app local development +App-by-app local setup: Server: - ```bash cd apps/server npm install @@ -34,7 +30,6 @@ npm run dev ``` Web: - ```bash cd apps/web npm install @@ -42,7 +37,6 @@ npm run dev ``` Agent: - ```bash cd apps/agent python -m venv .venv @@ -52,108 +46,84 @@ uvicorn main:app --host 0.0.0.0 --port 7001 ``` ## 3. Project Layout - -- `apps/web`: React/Vite frontend, node graph UI, diagnostics panels. -- `apps/server`: Express API, runner, scheduler, auth, stores, metrics. -- `apps/server/prisma`: schema + migrations. -- `apps/agent`: FastAPI desktop automation service. -- `docs`: architecture/API/deployment/contribution docs. -- `deploy/k8s`: Kubernetes starter manifests. - -## 4. Code Standards - -- TypeScript and Python code should be explicit and readable. -- Keep functions focused; avoid large multi-responsibility handlers. -- Prefer schema validation (`zod`) for new API inputs. -- For protected endpoints, always apply `requirePermission`. -- Write audit events for security-sensitive or admin actions. -- Keep log entries structured and actionable. -- Avoid introducing magic constants; use named config/env values. - -## 5. Testing Expectations - -## Backend tests - +- `apps/web`: React/Vite UI and workflow builder +- `apps/server`: Express API, runner, scheduler, auth, stores +- `apps/server/prisma`: schema and migrations +- `apps/agent`: FastAPI desktop bridge +- `docs`: architecture/API/deployment/onboarding + +## 4. Contribution Paths by Change Type + +### A. Web/UI Changes +- Touchpoints: `apps/web/src/*` +- Also update: screenshots/GIFs in PR for behavior changes +- Required validation: ```bash -docker compose run --rm server npm test +cd apps/web && npm test && npm run build ``` -Critical path subset: - +### B. Server/API/Runner Changes +- Touchpoints: `apps/server/src/*` +- Expectations: + - add input validation (`zod`) for new API contracts + - apply permission checks for protected endpoints + - write audit events for sensitive/admin operations +- Required validation: ```bash -docker compose run --rm server npm run test:critical +cd apps/server && npm test && npm run build ``` -Web UI tests: - +### C. Docs/Community Changes +- Touchpoints: `README.md`, `docs/*`, `.github/*template*` +- Expectations: + - commands and paths are runnable/accurate + - docs reflect current merged behavior + +## 5. Templates for Consistency +Use these templates when applicable: +- `docs/templates/activity-proposal.md` +- `docs/templates/node-implementation-checklist.md` +- `docs/templates/demo-script-template.md` + +## 6. Testing and CI +CI in `.github/workflows/ci.yml` runs on PRs and `main` pushes: +- `Server Test and Build` +- `Web Test and Build` +- `Web E2E Smoke` + +Recommended full local validation before review: ```bash -cd apps/web -npm test -``` - -Web E2E smoke tests (Playwright): - -```bash -cd apps/web -npx playwright install --with-deps chromium -npm run test:e2e +cd apps/server && npm test && npm run build +cd apps/web && npm test && npm run build ``` -Test locations: -- `apps/server/src/**/*.test.ts` - -When adding features: -- Add/extend unit tests for new logic. -- Add API behavior tests for validation/permission edges where feasible. -- For run-engine features, include success and failure-path coverage. - -CI gate: -- GitHub Actions workflow `.github/workflows/ci.yml` runs server/web test+build on every PR. -- CI also runs Playwright smoke tests (`Web E2E Smoke`). -- Keep CI green before asking for review or merge. - -Release flow: -- Use root scripts to tag next version from `main`: - - `npm run release:patch` - - `npm run release:minor` - - `npm run release:major` -- Tag push triggers `.github/workflows/release.yml`, which reruns verification and creates the GitHub release. -- Record user-facing changes in `CHANGELOG.md`. - -## 6. Manual QA Checklist - -Before submitting: -- [ ] Login/logout flow works. -- [ ] Workflow create/edit/save/publish works. -- [ ] Quick-add node search works (`Ctrl/Cmd+K`, type, `Enter`). -- [ ] Duplicate selected node works (`Ctrl+D` and toolbar button). -- [ ] Autopilot workflow generation works from sidebar prompt. -- [ ] Orchestrator robot/job queue flow works (create robot, queue job, dispatch/sync). -- [ ] Process mining panel loads and shows opportunities/bottlenecks. -- [ ] Test run and production run both work. -- [ ] Approval/resume behavior works for `manual_approval`. -- [ ] Run diagnostics logs/artifacts render correctly. -- [ ] Document understanding and clipboard AI transfer nodes validate and run as expected. -- [ ] New UI interactions show success/error feedback. -- [ ] No regressions in schedule and template flows. - -## 7. Pull Request Guidelines - -- Use focused commits and clear messages. -- Include what changed, why, and how to validate. -- Include screenshots/GIFs for UI behavior changes. -- Mention any migration or env var changes explicitly. -- Update `README.md`, `QUICKSTART.md`, and/or `docs/*` when behavior changes. - -## 8. Security and Secrets - -- Never commit real secrets or personal credentials. -- Use `.env.example` for new config keys. -- If adding auth, RBAC, webhook, or secret features, include abuse-case considerations and tests. - -## 9. Documentation Rule - -Feature work is not complete until: -- API changes are reflected in `docs/API_REFERENCE.md`. -- architecture-impacting changes are reflected in `docs/ARCHITECTURE.md`. -- deployment-impacting changes are reflected in `docs/DEPLOYMENT.md`. +## 7. Definition of Done +A PR is done only when all are true: +- [ ] Scope is focused and the title/description are clear. +- [ ] Required tests/build commands pass. +- [ ] API/UI behavior changes are documented. +- [ ] `CHANGELOG.md` updated for user-visible changes. +- [ ] Risk and rollback notes are included in PR. + +## 8. Pull Request Guidelines +- Branch naming: `feat/`, `fix/`, `docs/`. +- Commit messages: concise, imperative (`feat(recorder): add draft review panel`). +- Use `.github/pull_request_template.md`. +- Include: + - what changed and why + - exact validation commands run + - screenshots/GIFs for UI changes + - docs updated + +## 9. Release Flow +From `main`, create the next tag: +- `npm run release:patch` +- `npm run release:minor` +- `npm run release:major` + +Tag push triggers `.github/workflows/release.yml` and publishes GitHub release notes. + +## 10. Security and Secrets +- Never commit real secrets. +- Add new env vars to `.env.example`. +- For auth/RBAC/webhooks/secrets changes, include abuse-case considerations and tests. diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index 01cb8a8..ee75e5a 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -1,6 +1,6 @@ # Contributor Onboarding -This guide helps new contributors deliver a first high-quality PR quickly. +This guide helps new contributors ship a first high-quality PR quickly. ## 1. Prerequisites - Docker + Docker Compose @@ -20,51 +20,62 @@ Default local login: - username: `local` - password: `localpass` -## 3. Understand the Repo Fast -- `apps/web`: workflow studio UI -- `apps/server`: API, runner, scheduling, auth, orchestration -- `apps/agent`: desktop automation bridge -- `docs`: architecture, API, deployment, contribution docs - -## 4. Choose a First Task -Recommended starter contributions: -- UI improvements in `apps/web/src/components` -- Add/extend node behavior in `apps/server/src/lib/runner.ts` -- Add endpoint + tests in `apps/server/src/index.ts` + `src/lib/*.test.ts` -- Improve docs/tutorials in `docs/*` - -## 5. Development Workflow -1. Create branch +## 3. Do the 10-Minute Tutorial First +Use the guided tutorial and starter workflow: +- `docs/tutorials/FIRST_AUTOMATION_10_MIN.md` +- `docs/examples/workflows/first-automation.workflow.json` + +This gives you a known-good baseline before deeper changes. + +## 4. Choose a Contribution Track + +### Web/UI track +- Primary files: `apps/web/src/*` +- Typical work: canvas UX, inspector fields, sidebar features +- Required validation: ```bash -git checkout -b feat/ +cd apps/web && npm test && npm run build ``` -2. Implement change -3. Run validation: + +### Server/Runtime track +- Primary files: `apps/server/src/*` +- Typical work: runner nodes, APIs, authz, orchestrator logic +- Required validation: ```bash cd apps/server && npm test && npm run build -cd apps/web && npm test && npm run build ``` -4. Update docs for behavior/API changes -5. Commit with clear message (example: `feat(orchestrator): add queue status sync`) - -## 6. Pull Request Checklist -Use `.github/pull_request_template.md` and include: -- What changed and why -- How to test (exact commands) -- Screenshots/GIF for UI changes -- Docs updates performed -- Risk/rollback notes for non-trivial changes - -## 7. Community Standards in This Repo -- Keep commits focused and reviewable. -- Add tests for new logic and edge cases. -- Validate permissions for protected API changes. -- Write audit events for sensitive/admin actions. -- Keep docs current with features. + +### Docs/Enablement track +- Primary files: `README.md`, `docs/*`, `.github/*template*` +- Typical work: tutorials, examples, contribution process, demo scripts +- Required validation: link/command accuracy and consistency with current behavior + +## 5. Use Repository Templates +Start from templates in `docs/templates` when relevant: +- `activity-proposal.md` +- `node-implementation-checklist.md` +- `demo-script-template.md` + +## 6. Pull Request Path +1. Create branch: +```bash +git checkout -b feat/ +``` +2. Implement focused changes. +3. Run required validation for your track. +4. Update docs affected by behavior/API/UI changes. +5. Fill `.github/pull_request_template.md` completely. + +## 7. Definition of Done (Required) +- [ ] Changes are scoped and reviewable. +- [ ] Required tests/builds pass. +- [ ] User-facing/API behavior is documented. +- [ ] Demo/tutorial updates are included when UX flows change. +- [ ] PR includes rollback/risk notes. ## 8. Where to Ask Questions - Open a draft PR early with assumptions. -- Link relevant files and failing tests directly. -- Keep scope explicit to speed up review. +- Link exact files and failing commands. +- Keep scope explicit to reduce review churn. -Tip: prefer small PRs (<300 changed lines) to keep review cycles fast. +Tip: prefer small PRs (<300 changed lines) unless the feature requires a larger vertical slice. diff --git a/docs/README.md b/docs/README.md index 0294510..87c85d3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,9 @@ This folder contains the long-form technical documentation for operators and con - [Contributing Guide](./CONTRIBUTING.md): development setup, testing workflow, coding standards, and contribution process. - [Demo Guide](./DEMOS.md): repeatable walkthroughs for product capability demos. - [Contributor Onboarding](./ONBOARDING.md): fast path for first-time contributors. +- [First Automation Tutorial](./tutorials/FIRST_AUTOMATION_10_MIN.md): a 10-minute path from setup to successful test run. +- [Starter Workflow Example](./examples/workflows/first-automation.workflow.json): importable workflow file used in onboarding. +- [Contribution Templates](./templates): proposal/checklist/script templates for consistent PRs. - [Changelog](../CHANGELOG.md): release history and upgrade notes. Recent UX baseline: diff --git a/docs/examples/workflows/first-automation.workflow.json b/docs/examples/workflows/first-automation.workflow.json new file mode 100644 index 0000000..5a706e2 --- /dev/null +++ b/docs/examples/workflows/first-automation.workflow.json @@ -0,0 +1,62 @@ +{ + "schema": "forgeflow.workflow", + "version": 1, + "name": "Starter: First Automation", + "exportedAt": "2026-02-14T00:00:00.000Z", + "definition": { + "nodes": [ + { + "id": "start", + "type": "action", + "position": { "x": 80, "y": 120 }, + "data": { "type": "start", "label": "Start" } + }, + { + "id": "set-order-id", + "type": "action", + "position": { "x": 330, "y": 120 }, + "data": { + "type": "set_variable", + "label": "Set Order ID", + "key": "orderId", + "value": "PO-1001" + } + }, + { + "id": "set-order-status", + "type": "action", + "position": { "x": 580, "y": 120 }, + "data": { + "type": "set_variable", + "label": "Set Order Status", + "key": "orderStatus", + "value": "approved" + } + }, + { + "id": "validate-order-status", + "type": "action", + "position": { "x": 830, "y": 120 }, + "data": { + "type": "submit_guard", + "label": "Validate Order Status", + "inputKey": "orderStatus", + "schema": { + "type": "string", + "pattern": "^(approved|rejected)$" + } + } + } + ], + "edges": [ + { "id": "e-start-set-order-id", "source": "start", "target": "set-order-id" }, + { "id": "e-set-order-id-set-order-status", "source": "set-order-id", "target": "set-order-status" }, + { "id": "e-set-order-status-validate-order-status", "source": "set-order-status", "target": "validate-order-status" } + ], + "execution": { + "globalTimeoutMs": 1800000, + "defaultRetries": 2, + "defaultNodeTimeoutMs": 30000 + } + } +} diff --git a/docs/templates/activity-proposal.md b/docs/templates/activity-proposal.md new file mode 100644 index 0000000..b3aade5 --- /dev/null +++ b/docs/templates/activity-proposal.md @@ -0,0 +1,50 @@ +# Activity Proposal Template + +Use this when proposing a new built-in activity. + +## Activity Metadata +- Activity ID: `example_activity` +- Label: `Example Activity` +- Category: `Web|Data|AI|Desktop|Integrations|Control` +- Status: `available|planned` +- Owner: `@username` + +## Problem and User Outcome +- Problem this solves: +- Who benefits: +- Expected user-visible result: + +## API/Runtime Contract +- Required inputs: +- Optional inputs: +- Output keys / side effects: +- Failure modes and retry strategy: + +## Security and Governance +- Required permissions: +- Secrets handling: +- Audit event requirements: + +## Example Node Data +```json +{ + "type": "example_activity", + "label": "Example", + "inputKey": "source", + "outputKey": "result" +} +``` + +## Test Plan +- Unit tests to add: +- Edge/failure cases: +- Manual QA scenario: + +## Documentation Updates +- [ ] `docs/API_REFERENCE.md` +- [ ] `docs/DEMOS.md` (if demoable) +- [ ] `README.md` / `docs/README.md` (if user-facing) + +## Rollout/Risk Notes +- Backward compatibility: +- Rollback plan: diff --git a/docs/templates/demo-script-template.md b/docs/templates/demo-script-template.md new file mode 100644 index 0000000..19105ee --- /dev/null +++ b/docs/templates/demo-script-template.md @@ -0,0 +1,34 @@ +# Demo Script Template + +Use this template to add a repeatable product demo in `docs/DEMOS.md`. + +## Demo Title +- Name: +- Goal: +- Audience: +- Duration target: + +## Preconditions +- Required services/environment: +- Required sample data: +- Required permissions/role: + +## Script Steps +1. +2. +3. +4. +5. + +## Expected Outcome +- Functional result: +- UI signals to verify: +- Logs/metrics to verify: + +## Failure Recovery Notes +- Common failure: +- Quick fix: + +## Post-Demo Cleanup +- Data/flows to remove or reset: +- Follow-up links: diff --git a/docs/templates/node-implementation-checklist.md b/docs/templates/node-implementation-checklist.md new file mode 100644 index 0000000..f8beea5 --- /dev/null +++ b/docs/templates/node-implementation-checklist.md @@ -0,0 +1,35 @@ +# Node Implementation Checklist + +Use this checklist in PRs that add or change workflow node behavior. + +## Scope +- [ ] Node type and intent are clearly named. +- [ ] Inputs/outputs are documented. +- [ ] Backward compatibility impact is stated. + +## Server Implementation +- [ ] Runner case added/updated (`apps/server/src/lib/runner.ts`). +- [ ] Validation rules updated where needed. +- [ ] Permission checks applied for protected operations. +- [ ] Audit events added for sensitive actions. + +## Tests +- [ ] Success-path test added. +- [ ] Failure-path test added. +- [ ] Retry/timeout behavior tested when relevant. +- [ ] Existing tests still pass. + +## Web/UI +- [ ] Node appears in catalog (`apps/web/src/lib/nodeCatalog.ts`) if user-facing. +- [ ] Inspector fields added/updated for node config. +- [ ] UX copy and defaults are clear. + +## Documentation +- [ ] API/docs updated (`docs/API_REFERENCE.md` and related docs). +- [ ] Demo/onboarding docs updated if workflow changes are user-visible. +- [ ] Changelog updated. + +## Definition of Done +- [ ] `cd apps/server && npm test && npm run build` +- [ ] `cd apps/web && npm test && npm run build` +- [ ] PR includes validation commands and rollback note. diff --git a/docs/tutorials/FIRST_AUTOMATION_10_MIN.md b/docs/tutorials/FIRST_AUTOMATION_10_MIN.md new file mode 100644 index 0000000..c5ed996 --- /dev/null +++ b/docs/tutorials/FIRST_AUTOMATION_10_MIN.md @@ -0,0 +1,67 @@ +# First Automation in 10 Minutes + +This tutorial gets a new contributor from zero to a successful test run using a starter workflow. + +## 1. Start the stack (1 minute) + +```bash +./start.sh +``` + +Open: +- UI: `http://localhost:5173` +- API health: `http://localhost:8080/ready` + +Login with local defaults: +- Username: `local` +- Password: `localpass` + +## 2. Import the starter workflow (2 minutes) + +1. In the left sidebar, click `Load Workflow File`. +2. Select `docs/examples/workflows/first-automation.workflow.json`. +3. Confirm the workflow appears in the canvas. + +What this starter does: +- sets `orderId` +- sets `orderStatus` +- validates `orderStatus` with `submit_guard` + +## 3. Run in test mode (2 minutes) + +1. Click `Test Run` in the top toolbar. +2. Open the newest run in `Run Timeline`. +3. In `Run Diagnostics`, confirm status is `SUCCEEDED`. + +Expected result: +- All nodes succeed. +- No approval pause is required. + +## 4. Verify output context (2 minutes) + +In `Run Diagnostics` -> `Variable Inspector`, confirm values: +- `orderId`: `PO-1001` +- `orderStatus`: `approved` + +If `submit_guard` fails, check the schema in the node inspector and rerun. + +## 5. Make one intentional change (2 minutes) + +1. Edit `Set Order Status` value from `approved` to `rejected`. +2. Run `Test Run` again. +3. Confirm the run still passes. + +Now set it to `pending` and rerun. The run should fail at `Validate Order Status`. + +## 6. Save and document (1 minute) + +1. Click `Save Draft`. +2. Add a short note to your PR describing: +- what you changed +- why the guard passed/failed in each run + +## Troubleshooting + +- Recorder/browser dependencies are not required for this tutorial. +- If login fails, verify `.env` credentials and restart with `./start.sh`. +- If run fails before node execution, check preflight messages in the UI status area.