From c817ec3385c0b943fb1c8b6db2d33b43a39530a2 Mon Sep 17 00:00:00 2001 From: Anthony Wright Date: Thu, 9 Jul 2026 14:03:14 -0500 Subject: [PATCH] community readiness --- .github/ISSUE_TEMPLATE/accessibility_issue.md | 39 +++ .github/ISSUE_TEMPLATE/bug_report.md | 50 +++ .github/ISSUE_TEMPLATE/config.yml | 8 + .../educator_curriculum_feedback.md | 41 +++ .github/ISSUE_TEMPLATE/feature_request.md | 41 +++ .../good_first_issue_proposal.md | 38 +++ .../historical_accuracy_source_concern.md | 40 +++ .github/pull_request_template.md | 47 +++ ARCHITECTURE.md | 138 +++++++++ CODE_OF_CONDUCT.md | 43 +++ CONTRIBUTING.md | 164 ++++++++++ README.md | 285 ++++++++---------- ROADMAP.md | 68 +++++ SECURITY.md | 65 ++++ docs/community-trust.md | 91 ++++++ docs/github-community-setup.md | 77 +++++ docs/open-source-readiness-audit.md | 35 +++ docs/outreach-readiness.md | 122 ++++++++ docs/public-demo.md | 92 ++++++ .../.openspec.yaml | 2 + .../design.md | 107 +++++++ .../proposal.md | 34 +++ .../open-source-community-readiness/spec.md | 100 ++++++ .../tasks.md | 62 ++++ .../open-source-community-readiness/spec.md | 106 +++++++ 25 files changed, 1732 insertions(+), 163 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/accessibility_issue.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/educator_curriculum_feedback.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/good_first_issue_proposal.md create mode 100644 .github/ISSUE_TEMPLATE/historical_accuracy_source_concern.md create mode 100644 .github/pull_request_template.md create mode 100644 ARCHITECTURE.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 ROADMAP.md create mode 100644 SECURITY.md create mode 100644 docs/community-trust.md create mode 100644 docs/github-community-setup.md create mode 100644 docs/open-source-readiness-audit.md create mode 100644 docs/outreach-readiness.md create mode 100644 docs/public-demo.md create mode 100644 openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/.openspec.yaml create mode 100644 openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/design.md create mode 100644 openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/proposal.md create mode 100644 openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/specs/open-source-community-readiness/spec.md create mode 100644 openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/tasks.md create mode 100644 openspec/specs/open-source-community-readiness/spec.md diff --git a/.github/ISSUE_TEMPLATE/accessibility_issue.md b/.github/ISSUE_TEMPLATE/accessibility_issue.md new file mode 100644 index 0000000..15c43fd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/accessibility_issue.md @@ -0,0 +1,39 @@ +--- +name: Accessibility issue +about: Report an accessibility barrier in the app, docs, or demo +title: "Accessibility: " +labels: "accessibility, needs accessibility review" +assignees: "" +--- + +## Summary + +What accessibility barrier did you encounter? + +## Location + +- URL or route: +- File or document: +- Browser/device: + +## Impact + +Who is affected and how? + +## Assistive Technology + +If relevant, include screen reader, keyboard-only, browser zoom, voice control, or other tools used. + +## Steps to Reproduce + +1. +2. +3. + +## Suggested Fix + +If you have a suggestion, add it here. + +## Screenshots + +Add screenshots if useful. Do not include personal, student, school, or sensitive data. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..2c31132 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,50 @@ +--- +name: Bug report +about: Report something that is broken or behaving unexpectedly +title: "Bug: " +labels: "type: bug, needs triage" +assignees: "" +--- + +## Summary + +What is broken? + +## Steps to Reproduce + +1. +2. +3. + +## Expected Behavior + +What did you expect to happen? + +## Actual Behavior + +What happened instead? + +## Area + +- [ ] Public landing page +- [ ] Demo login +- [ ] Student experience +- [ ] Teacher experience +- [ ] Admin/content experience +- [ ] Backend/API +- [ ] Documentation +- [ ] Other + +## Environment + +- Browser: +- Device: +- URL or route: + +## Screenshots or Logs + +Add screenshots or logs if useful. Do not include personal, student, school, or sensitive data. + +## Notes + +Anything else maintainers should know? diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..185576b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: Security report + url: https://github.com/mrwrite/echoed/blob/main/SECURITY.md + about: Please report vulnerabilities through the security policy. + - name: Public demo guide + url: https://github.com/mrwrite/echoed/blob/main/docs/public-demo.md + about: Review demo roles, shared credentials, limitations, and feedback paths. diff --git a/.github/ISSUE_TEMPLATE/educator_curriculum_feedback.md b/.github/ISSUE_TEMPLATE/educator_curriculum_feedback.md new file mode 100644 index 0000000..5db3773 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/educator_curriculum_feedback.md @@ -0,0 +1,41 @@ +--- +name: Educator or curriculum feedback +about: Share bounded feedback on lesson flow, classroom fit, curriculum, or facilitation +title: "Educator feedback: " +labels: "educator feedback, curriculum, needs triage" +assignees: "" +--- + +## Your Context + +Role or perspective: + +Grade band or learner context: + +## What You Reviewed + +- [ ] Landing page +- [ ] Public demo guide +- [ ] Student demo flow +- [ ] Teacher demo flow +- [ ] Admin/content flow +- [ ] Specific lesson or activity: +- [ ] Other: + +## Feedback + +What felt useful? + +What felt unclear, inaccurate, inaccessible, or culturally off? + +What would make this more useful for educators or learners? + +## Suggested Change + +If you have a concrete suggestion, add it here. + +## Recognition + +- [ ] I am comfortable being publicly credited if this feedback leads to a visible change. +- [ ] Please do not publicly credit me. +- [ ] Ask me first. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..958eaa1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,41 @@ +--- +name: Feature request +about: Suggest a feature or improvement +title: "Feature: " +labels: "type: feature, needs triage" +assignees: "" +--- + +## Summary + +What should EchoEd add or improve? + +## Problem + +What problem would this solve? + +## Audience + +- [ ] Student +- [ ] Educator +- [ ] Parent/family +- [ ] School or organization admin +- [ ] Contributor/developer +- [ ] Community organizer + +## Proposed Direction + +Describe the smallest useful version of this feature. + +## Alternatives + +What could work instead? + +## Acceptance Criteria + +- [ ] +- [ ] + +## Notes + +Include links, examples, or context if useful. diff --git a/.github/ISSUE_TEMPLATE/good_first_issue_proposal.md b/.github/ISSUE_TEMPLATE/good_first_issue_proposal.md new file mode 100644 index 0000000..f8acb28 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/good_first_issue_proposal.md @@ -0,0 +1,38 @@ +--- +name: Good first issue proposal +about: Propose a small, beginner-friendly task +title: "Good first issue: " +labels: "good first issue, needs triage" +assignees: "" +--- + +## Task + +What small task should a new contributor be able to complete? + +## Area + +- [ ] Documentation +- [ ] Frontend +- [ ] Backend +- [ ] Testing +- [ ] Accessibility +- [ ] Demo +- [ ] Curriculum tooling + +## Suggested Files or Routes + +List likely files, folders, or routes. + +## Acceptance Criteria + +- [ ] +- [ ] + +## Validation + +How should a contributor know the task is complete? + +## Notes for First-Time Contributors + +Add any context that would help someone new. diff --git a/.github/ISSUE_TEMPLATE/historical_accuracy_source_concern.md b/.github/ISSUE_TEMPLATE/historical_accuracy_source_concern.md new file mode 100644 index 0000000..cd21548 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/historical_accuracy_source_concern.md @@ -0,0 +1,40 @@ +--- +name: Historical accuracy or source concern +about: Report a historical, source, cultural framing, or curriculum accuracy concern +title: "Historical review: " +labels: "historical accuracy, curriculum, needs historical review" +assignees: "" +--- + +## Concern + +What appears inaccurate, weakly sourced, overgeneralized, or culturally concerning? + +## Location + +Where did you see it? + +- URL or route: +- Lesson, activity, or document: +- Screenshot or quoted excerpt if useful: + +## Why It Matters + +Explain the historical, cultural, learner, or classroom impact. + +## Suggested Sources or Framing + +If you have suggested sources, terminology, or framing, add them here. This is helpful but not required. + +## Urgency + +- [ ] Blocks public sharing +- [ ] Needs review before classroom use +- [ ] Improvement or clarification +- [ ] Question for maintainers + +## Recognition + +- [ ] I am comfortable being publicly credited if this feedback leads to a visible change. +- [ ] Please do not publicly credit me. +- [ ] Ask me first. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..5373e31 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,47 @@ +# Summary + +What changed? + +# Motivation + +Why is this change needed? + +# Type of Change + +- [ ] Documentation +- [ ] Frontend +- [ ] Backend +- [ ] Tests +- [ ] Accessibility +- [ ] Demo +- [ ] Curriculum/community review +- [ ] Other + +# Test Plan + +List the checks you ran. + +- [ ] Backend tests +- [ ] Frontend build +- [ ] Frontend unit tests +- [ ] Demo smoke test +- [ ] Manual review +- [ ] Not run. Explain below. + +If you could not run a check, explain why: + +# Screenshots + +Add screenshots for visible UI changes. + +# Accessibility Check + +Describe any accessibility impact, including keyboard, contrast, labels, readable text, and mobile layout where relevant. + +# Community or Curriculum Impact + +Does this affect educator review, historical accuracy, source quality, learner experience, community language, or contribution flow? + +# Notes + +Anything maintainers should know? diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..8decfcf --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,138 @@ +# EchoEd Architecture + +EchoEd is a full-stack education platform with a separate Angular frontend and FastAPI backend. + +## System Overview + +```text +frontend/ Angular app + | + | HTTP API calls, proxied locally through frontend/proxy.conf.json + v +backend/ FastAPI app + | + | SQLAlchemy models and Alembic migrations + v +PostgreSQL or local development database +``` + +The repository also includes: +- `docs/` for runbooks and public project guidance. +- `openspec/` for spec-driven planning and validation. +- `curriculum/` for curriculum source and seed material. +- `backend/scripts/reseed_demo.py` for deterministic demo data. + +## Frontend + +Location: `frontend/` + +Primary technologies: +- Angular +- Tailwind CSS and SCSS +- Playwright for demo smoke testing +- Karma/Jasmine for Angular tests + +Important paths: +- `frontend/src/app/pages/landing/` public landing page +- `frontend/src/app/pages/login/` login flow +- `frontend/src/app/pages/registration/` registration flow +- `frontend/src/app/pages/user-dashboard/` student, teacher, and admin surfaces +- `frontend/src/app/shared/lesson-viewer.*` shared lesson rendering +- `frontend/src/environments/` environment API settings +- `frontend/tests/demo/` browser smoke tests + +Local frontend API calls use `frontend/proxy.conf.json` to reach the backend at `http://127.0.0.1:8000`. + +## Backend + +Location: `backend/` + +Primary technologies: +- FastAPI +- SQLAlchemy +- Alembic +- pytest +- JWT-based authentication + +Important paths: +- `backend/app/main.py` wires the API. +- `backend/app/models.py` contains SQLAlchemy models. +- `backend/app/schemas.py` contains request and response schemas. +- `backend/app/auth.py` contains authentication logic. +- `backend/app/database.py` configures database access. +- `backend/app/api/routes/` contains route modules. +- `backend/app/crud/` contains domain helper functions where present. +- `backend/alembic/versions/` contains database migrations. +- `backend/tests/` contains the backend test suite. + +## Existing Domain Boundaries + +Reuse existing systems before adding new ones: +- Authentication: `backend/app/auth.py`, `backend/app/api/routes/auth.py` +- Organizations: `backend/app/api/routes/orgs.py` +- Courses and lessons: `courses.py`, `units.py`, `lessons.py`, `activities.py` +- Progress and learning runtime: `progress.py`, `start_course.py`, `lesson_sessions.py` +- Sections and assignments: `sections.py`, `assignments.py` +- Forum-style discussion: `posts.py`, `threads.py` +- Uploads and assets: `uploads.py` +- V2 workspace/product wrappers: `v2_platform.py` + +Do not create parallel auth, organization, progress, lesson, or onboarding systems. + +## Demo Seed System + +The deterministic demo is reset with: + +```powershell +backend\venv\Scripts\python.exe backend\scripts\reseed_demo.py +``` + +The operator runbook is [docs/demo-readiness.md](docs/demo-readiness.md). The public evaluation guide is [docs/public-demo.md](docs/public-demo.md). + +## OpenSpec Workflow + +OpenSpec changes live in `openspec/changes/`. + +Useful commands: + +```powershell +cmd /c openspec status --change "" --json +cmd /c openspec validate --strict +cmd /c openspec instructions apply --change "" --json +``` + +In this repository, implementation is performed by working through the task file for a change and checking off completed tasks. There is no `openspec apply` CLI subcommand. + +## Testing Strategy + +Backend tests: + +```powershell +cd backend +pytest +``` + +Frontend build: + +```powershell +cd frontend +cmd /c npm run build +``` + +Frontend unit tests: + +```powershell +cd frontend +cmd /c .\node_modules\.bin\ng.cmd test --watch=false --browsers=ChromeHeadless +``` + +Demo smoke: + +```powershell +cd frontend +cmd /c .\node_modules\.bin\playwright.cmd test tests/demo/student-flagship-smoke.spec.ts +``` + +## Contribution Guidance + +Changes should be small, scoped, and aligned with existing boundaries. Documentation-only changes do not need backend migrations or frontend tests, but they should still pass OpenSpec validation when tied to an OpenSpec change. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..623173c --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,43 @@ +# Code of Conduct + +EchoEd is an open-source education project centered on African and African-American history. The community must be respectful, inclusive, and careful with culturally significant educational work. + +## Expected Behavior + +Participants are expected to: +- Communicate with respect. +- Welcome educators, developers, students, organizers, and reviewers with different levels of technical experience. +- Give specific, constructive feedback. +- Respect boundaries around unpaid labor and review capacity. +- Be careful with historical, cultural, and identity-related claims. +- Credit contributions when requested and appropriate. +- Follow accessibility and inclusion expectations in docs, UI, and learning content. + +## Unacceptable Behavior + +Unacceptable behavior includes: +- Harassment, intimidation, threats, or personal attacks. +- Racist, sexist, homophobic, transphobic, ableist, or otherwise discriminatory language. +- Dismissive treatment of educator, student, diaspora, or community perspectives. +- Publishing private information without permission. +- Using demo accounts for abusive, destructive, or non-demo purposes. +- Repeatedly demanding unpaid labor, review, or response from community members. +- Misrepresenting EchoEd's current maturity, review status, or educational authority. + +## Historical and Cultural Care + +Because EchoEd deals with African and African-American history, participants should treat content review seriously. If you see a historical accuracy issue, source concern, cultural framing concern, or accessibility issue, report it through the relevant issue template or contact path. + +## Enforcement + +Reports can be sent to: + +```text +support@echoed.com +``` + +Maintainers may remove comments, close issues, reject contributions, or limit participation when conduct harms the project or community. + +## Scope + +This code applies to repository activity, issues, pull requests, discussions, public outreach related to EchoEd, and project communication channels controlled by EchoEd maintainers. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ce1c051 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,164 @@ +# Contributing to EchoEd + +Thank you for considering a contribution. EchoEd is early, open source, and preparing for public community outreach. Contributions are welcome, but asks should stay specific, bounded, and respectful of people's time. + +## Ways to Contribute + +Useful Phase 1 contributions include: +- Documentation improvements. +- Setup and onboarding fixes. +- Educator or curriculum review. +- Historical accuracy or source review. +- Accessibility review. +- Frontend polish. +- Backend tests. +- Demo reliability improvements. +- Good-first-issue cleanup. + +## First Contribution Workflow + +1. Read [README.md](README.md), [ARCHITECTURE.md](ARCHITECTURE.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). +2. Pick a small issue labeled `good first issue`, `documentation`, `accessibility`, `frontend`, `backend`, `testing`, `demo`, or `educator feedback`. +3. Comment on the issue before starting if the scope is unclear. +4. Create a focused branch. +5. Make the smallest change that solves the issue. +6. Run the relevant checks. +7. Open a pull request using the template. + +## Local Backend Setup + +```powershell +cd backend +python -m venv venv +venv\Scripts\activate +pip install -r requirements.txt +alembic upgrade head +uvicorn app.main:app --reload +``` + +## Local Frontend Setup + +```powershell +cd frontend +npm install +npm start +``` + +The frontend runs at `http://localhost:4200`. The backend runs at `http://127.0.0.1:8000`. + +## Environment Variables + +Create `.env` in the repository root: + +```env +DATABASE_URL=postgresql://echoed_user:your_secure_password@localhost/echoed +STORYBOOK_PATH=./storybook +COLORINGS_PATH=./colorings +BADGES_PATH=./badges +JWT_SECRET=your_jwt_secret +FRONTEND_URL=http://localhost:4200 +``` + +Do not commit real secrets. + +## Demo Seed Data + +To reset deterministic demo data: + +```powershell +backend\venv\Scripts\python.exe backend\scripts\reseed_demo.py +``` + +Use [docs/demo-readiness.md](docs/demo-readiness.md) for operator setup and [docs/public-demo.md](docs/public-demo.md) for public evaluation. + +## Testing + +Run the checks relevant to your change. + +Backend: + +```powershell +cd backend +pytest +``` + +Frontend build: + +```powershell +cd frontend +cmd /c npm run build +``` + +Frontend unit tests: + +```powershell +cd frontend +cmd /c .\node_modules\.bin\ng.cmd test --watch=false --browsers=ChromeHeadless +``` + +Demo smoke: + +```powershell +cd frontend +cmd /c .\node_modules\.bin\playwright.cmd test tests/demo/student-flagship-smoke.spec.ts +``` + +If you cannot run a check, say so in your pull request and explain why. + +## Pull Request Expectations + +Every pull request should include: +- What changed. +- Why it changed. +- How it was tested. +- Screenshots for visible UI changes. +- Accessibility notes for UI, docs, and content changes. +- Curriculum or community impact notes when relevant. + +## Good First Issue Structure + +Good starter issues should include: +- Clear problem statement. +- Files or area likely involved. +- Expected outcome. +- Acceptance criteria. +- Suggested validation. +- Whether educator, historical accuracy, accessibility, frontend, backend, docs, or testing review is needed. + +Example: + +```text +Title: Docs: clarify frontend setup for Windows contributors +Area: documentation +Files: CONTRIBUTING.md, frontend/README.md +Acceptance criteria: +- Windows setup commands are accurate. +- npm PowerShell execution-policy workaround is documented if needed. +- No product code changes. +Validation: +- Read the setup section and confirm commands are copyable. +``` + +## Educator and Curriculum Feedback + +Educator feedback is valuable and should be bounded. Good feedback includes: +- Which demo role or lesson you reviewed. +- Grade or learner context. +- What felt useful. +- What felt unclear, inaccurate, inaccessible, or culturally off. +- Suggested changes or questions. + +Use the educator/curriculum feedback issue template when possible. + +## Communication Guidelines + +- Be specific and respectful. +- Assume people are contributing with limited time. +- Avoid broad requests for unpaid labor. +- Do not claim classroom readiness or historical authority without review. +- Keep feedback focused on the work, not the person. +- Follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). + +## Maintainer Capacity + +EchoEd currently has no paid budget and no formal contributor program. Review times may vary. The project will prioritize small, clear, mission-aligned contributions. diff --git a/README.md b/README.md index c2db616..a22b7a5 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,98 @@ # EchoEd -[![CI](https://github.com/YOUR_USERNAME/EchoEd/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_USERNAME/EchoEd/actions/workflows/ci.yml) [![Docker](https://github.com/YOUR_USERNAME/EchoEd/actions/workflows/docker.yml/badge.svg)](https://github.com/YOUR_USERNAME/EchoEd/actions/workflows/docker.yml) - -**Echoing the Past, Educating the Future** - -EchoEd is an interactive web and mobile platform designed to educate all ages on African and African-American history. Featuring engaging lessons, gamification, and an interactive timeline, EchoEd makes learning history immersive and accessible. - ---- - -## ๐Ÿš€ Features -- **Curated Lessons & Modules** โ€“ Short, digestible lessons with media-rich content. -- **Interactive Timeline** โ€“ Explore key historical events dynamically. -- **Gamification & Achievements** โ€“ Earn badges, track progress, and compete on leaderboards. -- **Community Forum** โ€“ Discuss historical topics and engage in "Ask a Historian" sessions. -- **Oral Storytelling** โ€“ Audio narratives to preserve historical traditions. -- **Future AR Features** โ€“ Experience history through augmented reality. - ---- - -## ๐Ÿ›  Tech Stack -### **Frontend:** -- **Framework:** Angular -- **Styling:** TailwindCSS / Material UI - -### **Backend:** -- **Framework:** FastAPI (Python) -- **Database:** PostgreSQL -- **Authentication:** JWT-based authentication - -### **Infrastructure:** -- **Hosting:** AWS / DigitalOcean -- **CI/CD:** GitHub Actions (Planned) - ---- - -## ๐Ÿ“ฆ Project Structure -```bash -EchoEd/ -โ”‚โ”€โ”€ frontend/ # Angular Web & Mobile UI -โ”‚โ”€โ”€ backend/ # FastAPI API & Database -โ”‚โ”€โ”€ docs/ # Pitch Deck, Branding Assets, UI Mockups -โ”‚ โ””โ”€โ”€ design-guidelines.md # UI inspiration notes -โ”‚โ”€โ”€ assets/ # Logos, Icons, Images -โ”‚โ”€โ”€ tests/ # Automated tests -โ”‚โ”€โ”€ README.md # Overview & instructions -โ”‚โ”€โ”€ .gitignore # Ignore unnecessary files -โ”‚โ”€โ”€ LICENSE # Open-source license -``` ---- +EchoEd is an open-source education platform centered on African and African-American history. It is being prepared for public community review and contribution from educators, developers, students, homeschool leaders, HBCU communities, and community learning organizers across the United States, Africa, and the Caribbean. + +Current public app: https://echoed-theta.vercel.app/ +Repository: https://github.com/mrwrite/echoed +License: [MIT](LICENSE) + +## Current Status + +EchoEd is early and pre-community-launch. + +- Working K-5 demo exists with student, teacher, and admin experiences. +- Demo access uses shared demo-only credentials. +- The project has no current public users, contributors, stars, advisors, or community traction. +- Phase 1 focuses on trust, documentation, contributor onboarding, and public demo readiness before broad outreach begins. + +Do not enter personal, student, school, or production data into the demo. + +## Mission + +EchoEd exists to make culturally grounded Black history learning experiences easier to explore, teach, review, and improve in public. The project aims to combine rigorous historical learning, accessible product design, and open-source community ownership. + +## Who This Is For + +### Educators + +EchoEd needs classroom judgment before it needs scale. Educators can help by reviewing demo flows, lesson tone, age fit, source needs, discussion prompts, and classroom usefulness. + +Start here: +- Try the [public demo guide](docs/public-demo.md). +- File educator or curriculum feedback using the GitHub issue templates. +- Read the [community trust guide](docs/community-trust.md) for review expectations and recognition. -## ๐Ÿ”ง Installation & Setup -### **1๏ธโƒฃ Clone the Repository** -```sh -git clone https://github.com/YOUR_USERNAME/EchoEd.git -cd EchoEd +### Developers + +EchoEd is an Angular and FastAPI application. Developers can help with frontend polish, accessibility, backend tests, demo reliability, documentation, curriculum tooling, and contributor onboarding. + +Start here: +- Read [CONTRIBUTING.md](CONTRIBUTING.md). +- Review [ARCHITECTURE.md](ARCHITECTURE.md). +- Look for issues labeled `good first issue`, `help wanted`, `documentation`, `frontend`, `backend`, `testing`, `accessibility`, or `demo`. + +### Community Organizers + +Community organizers can help connect EchoEd with Black educator networks, homeschool groups, HBCU programs, Black developer groups, and Africa or Caribbean education technology communities. + +Start here: +- Review [docs/outreach-readiness.md](docs/outreach-readiness.md). +- Share bounded feedback or introductions through GitHub issues or `support@echoed.com`. + +## Public Demo + +The live app is available at https://echoed-theta.vercel.app/. + +Use the demo only for evaluation. Demo credentials and walkthrough steps are documented in [docs/public-demo.md](docs/public-demo.md). The credentials are shared, demo-only, resettable, and not appropriate for real learner data. + +## Project Structure + +```text +backend/ FastAPI app, SQLAlchemy models, Alembic migrations, pytest tests +frontend/ Angular app, Tailwind styling, Playwright demo smoke tests +docs/ Demo, outreach, and project guidance +openspec/ Spec-driven change workflow +curriculum/ Seed curriculum and package material ``` -### **2๏ธโƒฃ Backend Setup (FastAPI)** -```sh +For a deeper overview, see [ARCHITECTURE.md](ARCHITECTURE.md). + +## Local Development + +### Backend + +```powershell cd backend python -m venv venv -source venv/bin/activate # (Windows: venv\Scripts\activate) +venv\Scripts\activate pip install -r requirements.txt alembic upgrade head uvicorn app.main:app --reload ``` -Seed demo data: -```sh -python -m app.seed_demo -``` - -Deterministic live-demo preparation: -```sh -backend\venv\Scripts\python.exe backend\scripts\reseed_demo.py -``` -See [docs/demo-readiness.md](docs/demo-readiness.md) for the operator runbook, demo accounts, learner archetypes, and expected outcomes. +### Frontend -### **3๏ธโƒฃ Frontend Setup (Angular)** -```sh +```powershell cd frontend npm install -ng serve +npm start ``` -The Angular dev server proxies `/api` requests to `http://127.0.0.1:8000` via `frontend/proxy.conf.json`, so keep the backend running locally when working in dev mode. - -### **Setting Build Environments** -Angular uses environment files in `frontend/src/environments` to change values during different builds. The default `ng serve` uses `environment.ts`. To build with the production settings from `environment.prod.ts`, run: -```sh -ng build --configuration production -``` +The frontend dev server runs at `http://localhost:4200` and proxies API calls to `http://127.0.0.1:8000` through `frontend/proxy.conf.json`. -You can add more environment files (e.g., `environment.staging.ts`) and reference them with `--configuration ` once configured in `angular.json`. +### Environment -## ๐Ÿ—’๏ธ Environment Variables -The backend loads configuration from a `.env` file using **python-dotenv**. Create a file named `.env` in the project root with values like: +Create a `.env` file in the repository root for backend settings: ```env DATABASE_URL=postgresql://echoed_user:your_secure_password@localhost/echoed @@ -106,107 +103,69 @@ JWT_SECRET=your_jwt_secret FRONTEND_URL=http://localhost:4200 ``` -- `DATABASE_URL` โ€“ Connection string used by `database.py` to initialize the database. -- `STORYBOOK_PATH` โ€“ Folder for uploaded storybook pages. `main.py` exposes it at `/storybook`. -- `COLORINGS_PATH` โ€“ Folder for coloring pages served at `/colorings`. -- `BADGES_PATH` โ€“ Folder for badge images served at `/badges`. -- `JWT_SECRET` โ€“ Secret key used for signing JSON Web Tokens. -- `FRONTEND_URL` โ€“ Allowed origin(s) for CORS. Use a comma-separated list for multiple URLs. -- `STORYBOOK_PATH`, `COLORINGS_PATH`, `BADGES_PATH` โ€“ File storage locations for uploads. - -> **Org Context Header:** Most org-scoped endpoints require `X-Org-Id` to be set by the frontend (handled by the org interceptor). - -If any variable is omitted, the application falls back to the example values above. - -## ๐Ÿณ Docker Compose -1. Create a `.env` file in the project root with the variables above. -2. Build and start the stack: - ```sh - docker compose up --build - ``` - This spins up the FastAPI backend along with PostgreSQL and MinIO. -3. Access the API at [http://localhost:8000/docs](http://localhost:8000/docs). ---- - -## ๐Ÿš€ Usage -- **Run Frontend:** Open [http://localhost:4200](http://localhost:4200) -- **Run Backend API:** Open [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) for API documentation - - The `/api/start-course` endpoint now returns `400` with `"Course already completed"` if the user tries to start a finished course. - -## ๐Ÿงช Running Tests - -### **Backend** -```sh +See [CONTRIBUTING.md](CONTRIBUTING.md) for full setup, seed, and test guidance. + +## Demo Data + +To reset deterministic demo users, content, and learner states: + +```powershell +backend\venv\Scripts\python.exe backend\scripts\reseed_demo.py +``` + +Internal operator details live in [docs/demo-readiness.md](docs/demo-readiness.md). Public-facing demo instructions live in [docs/public-demo.md](docs/public-demo.md). + +## Testing + +Backend: + +```powershell cd backend pytest ``` -Generate coverage: -```sh -pytest --cov=app --cov-report=term-missing -``` +Frontend build: -### **Frontend** -```sh +```powershell cd frontend -ng test -``` - -Generate coverage: -```sh -ng test --code-coverage +cmd /c npm run build ``` ---- - -## ๐Ÿงญ Platform Roles & Core Flows +Frontend tests: -### **Platform roles** -- `super_admin` โ€“ Global platform control, diagnostics, and ops. +```powershell +cd frontend +cmd /c .\node_modules\.bin\ng.cmd test --watch=false --browsers=ChromeHeadless +``` -### **Organization roles** -- `org_admin` โ€“ Manages org settings, invites, and staffing. -- `content_admin` โ€“ Authors and publishes courses. -- `teacher` โ€“ Manages sections and assignments (in-person or remote). -- `parent` โ€“ Monitors student progress and supports learning at home. -- `student` โ€“ Consumes courses and completes activities. -- `instructor` โ€“ Higher-ed teaching role (remote-first). -- `viewer` โ€“ Read-only access for observers/guests. +Student demo smoke test: -### **Key flows** -1. **Organization setup** โ†’ New users can create an org during registration or complete the onboarding screen after login. Users with only a Personal Org are prompted to create a real org before continuing. -2. **Invitations** โ†’ Org admins invite users; accepted invites create memberships. -3. **Course authoring** โ†’ Content admins create course containers, draft versions, and publish immutable versions. -4. **Sections** โ†’ Teachers create sections linked to a course version and enroll learners. -5. **Learning** โ†’ Students enroll, resume progress by unit/lesson/activity, and earn badges. -6. **Assignments & sessions** โ†’ Teachers assign units/lessons, start live sessions, and review progress summaries. ---- +```powershell +cd frontend +cmd /c .\node_modules\.bin\playwright.cmd test tests/demo/student-flagship-smoke.spec.ts +``` -## ๐Ÿค Contributing -We welcome contributions! To contribute: -1. Fork the repository. -2. Create a new branch (`feature-branch`). -3. Commit your changes and push to your fork. -4. Open a Pull Request (PR). +## Contributing ---- +EchoEd welcomes bounded, respectful contributions. Because this project is early and has no paid budget, contribution requests should be specific and transparent. -## ๐Ÿ“œ License -This project is licensed under the **MIT License** โ€“ see the [LICENSE](LICENSE) file for details. +Read: +- [CONTRIBUTING.md](CONTRIBUTING.md) +- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) +- [SECURITY.md](SECURITY.md) +- [ROADMAP.md](ROADMAP.md) +- [docs/community-trust.md](docs/community-trust.md) ---- +## Roadmap -## ๐ŸŽจ Design Inspiration -Looking for styling tips? Check out [docs/design-guidelines.md](docs/design-guidelines.md) for notes on giving EchoEd a look similar to popular course platforms like Udemy or Pluralsight. +The current priority is Phase 1 public open-source readiness. See [ROADMAP.md](ROADMAP.md) for staged priorities. ---- +## Contact -## ๐Ÿ“ฌ Contact & Community -- **Website:** [Coming Soon] -- **Email:** support@echoed.com -- **GitHub Issues:** Report bugs or request features in the [Issues tab](https://github.com/YOUR_USERNAME/EchoEd/issues). -- **Follow Us:** [Twitter](#) | [LinkedIn](#) +- General community contact: support@echoed.com +- Security reports: see [SECURITY.md](SECURITY.md) +- Bugs, feedback, and contribution ideas: use GitHub issues ---- +## License -Let's **Echo the Past & Educate the Future** together! ๐ŸŒ๐Ÿ“š +EchoEd is licensed under the [MIT License](LICENSE). Copyright 2025 Anthony Wright. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..b34c650 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,68 @@ +# EchoEd Roadmap + +This roadmap is intentionally staged. EchoEd is early and should earn trust before broad outreach or scale. + +## Phase 1: Public Open-Source Readiness + +Goal: make EchoEd trustworthy, understandable, and contributor-ready before major outreach. + +Required outcomes: +- README explains the mission, status, demo, setup, contribution paths, and license. +- Community files exist: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `ARCHITECTURE.md`, and this roadmap. +- GitHub issue templates and PR template support bug reports, educator feedback, historical accuracy concerns, accessibility issues, and contributor proposals. +- Public demo guide explains safe demo use, roles, limitations, and feedback paths. +- Community trust guide defines educator review, historical accuracy review, accessibility expectations, recognition, and non-extractive participation. +- Outreach readiness guide defines the checklist to complete before contacting educators, HBCUs, developer communities, and organizers. + +## Phase 2: First Review Cohort + +Goal: run a small, bounded review cohort before public launch-style promotion. + +Candidate work: +- Invite 5 to 10 educators or curriculum reviewers to try the demo. +- Invite 3 to 5 developers to test setup and first contribution flow. +- Convert repeated feedback into labeled issues. +- Create and maintain a small set of `good first issue` tasks. +- Add screenshots or a short walkthrough video if manual screenshots are not enough. +- Decide whether to enable GitHub Discussions based on early volume. + +## Phase 3: Contributor Foundation + +Goal: make contribution repeatable. + +Candidate work: +- Improve local setup based on contributor friction. +- Add more focused tests around demo-critical flows. +- Expand accessibility checks. +- Add contributor recognition to README or release notes. +- Publish a monthly project update while activity exists. + +## Phase 4: Curriculum and Review Depth + +Goal: strengthen historical rigor and educator usefulness. + +Candidate work: +- Add a documented source review workflow. +- Create lesson review checklists for educators. +- Define review states for curriculum feedback. +- Add clearer guidance for African, African-American, Caribbean, and diaspora framing. +- Build a small advisory circle if there is sustained participation and capacity. + +## Later Product Priorities + +These are not Phase 1 requirements: +- Broader grade-band content. +- Richer educator dashboards. +- More learner activities and assessments. +- More durable demo automation. +- Public community discussion infrastructure. +- Production user onboarding. +- Payments, marketplace, or monetization. + +## Roadmap Principles + +- Trust before scale. +- Bounded asks before broad asks. +- Educator review before classroom claims. +- Accessibility and historical accuracy are part of quality, not polish. +- Open-source contribution paths should be specific enough that people know how to help. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..30d7973 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,65 @@ +# Security Policy + +EchoEd is early and pre-community-launch. Please report security concerns responsibly and do not test against systems or data you do not own. + +## Supported Scope + +Security reports may cover: +- Authentication and session handling. +- Authorization or role access issues. +- Exposure of secrets, tokens, or sensitive configuration. +- Demo credential misuse risks. +- Unsafe file upload behavior. +- Cross-site scripting, injection, or data exposure concerns. +- Vulnerabilities in documented setup or deployment instructions. + +## Reporting a Vulnerability + +Send security reports to: + +```text +support@echoed.com +``` + +Please include: +- A clear description of the issue. +- Steps to reproduce if safe to share. +- The affected URL, route, file, or component. +- Impact and suggested severity. +- Whether any data may have been exposed. + +Do not include real student, school, personal, or sensitive data in a report. + +## Demo Credential Policy + +EchoEd currently uses shared demo credentials for evaluation. These accounts are demo-only, resettable, and not intended for real use. + +Do not: +- Enter personal, student, school, or production data into demo accounts. +- Treat demo accounts as private workspaces. +- Use demo access for destructive, abusive, or load-testing behavior. +- Attempt to access non-demo data. + +If demo credentials appear to expose sensitive data, report it immediately through the security contact above. + +## Maintainer Response + +This is a no-budget early project, so response time may vary. The intended response process is: + +1. Acknowledge the report when possible. +2. Triage severity and reproducibility. +3. Fix or mitigate the issue. +4. Credit the reporter if they want recognition and disclosure is appropriate. + +## Public Disclosure + +Please do not publicly disclose a suspected vulnerability until there has been a reasonable opportunity to investigate and mitigate it. + +## Out of Scope + +The following are out of scope unless they demonstrate a concrete security impact: +- Generic scanner output without reproduction. +- Social engineering. +- Denial-of-service testing. +- Physical attacks. +- Reports against third-party services not controlled by EchoEd. diff --git a/docs/community-trust.md b/docs/community-trust.md new file mode 100644 index 0000000..5e92b66 --- /dev/null +++ b/docs/community-trust.md @@ -0,0 +1,91 @@ +# Community Trust Guide + +EchoEd asks for community help carefully because the project is centered on African and African-American history and currently has no paid budget. + +## Non-Extractive Participation + +When EchoEd asks educators, reviewers, developers, or community organizers for help, the ask should be: +- Specific: what should be reviewed or built. +- Bounded: how much time or scope is expected. +- Transparent: the project stage and no-budget status are clear. +- Optional: no one is pressured to contribute. +- Recognized: contributors can opt into public credit when appropriate. + +Avoid broad asks like "please review the curriculum" without a defined lesson, flow, or question. + +## Educator Review Process + +Educators can review: +- Lesson flow and grade fit. +- Learner instructions and tone. +- Cultural framing. +- Discussion prompts. +- Source needs. +- Classroom usefulness. +- Accessibility and learner support. + +How to submit review: +1. Try the demo using [public-demo.md](public-demo.md). +2. Use the educator/curriculum feedback issue template. +3. Include role context, grade context, the reviewed flow, and concrete feedback. + +Maintainer triage: +- Confirm whether the feedback is docs, content, UX, accessibility, or product behavior. +- Link repeated feedback to an issue. +- Ask follow-up questions only when needed. +- Credit reviewers if they request recognition and the contribution is public. + +## Historical Accuracy Review + +Historical and cultural concerns should be handled with care. + +Use the historical accuracy or source concern issue template for: +- Incorrect dates, names, events, geography, or terminology. +- Missing or weak sources. +- Unclear distinction between fact, interpretation, and activity framing. +- Overgeneralized African, African-American, Caribbean, or diaspora framing. +- Content that feels culturally disrespectful or age-inappropriate. + +Expected handling: +- Do not dismiss the concern as subjective without review. +- Ask for source suggestions if the reporter has them, but do not require unpaid source gathering. +- Track the issue visibly. +- Update content, docs, or known limitations when appropriate. + +## Contributor Recognition + +Recognition options may include: +- GitHub contributor history. +- README acknowledgements when requested. +- Release notes or project update mentions. +- Issue or PR credit. +- Advisory circle acknowledgement if a circle is formed later. + +Contributors may also choose not to be named. + +## Advisory Circle Concept + +EchoEd may form a small advisory circle later if there is enough sustained interest and maintainer capacity. + +Potential advisory perspectives: +- K-5 educators. +- African-American studies educators. +- African, Caribbean, and diaspora history reviewers. +- Accessibility reviewers. +- Black software developers and open-source maintainers. +- Homeschool or community learning organizers. + +This is a concept, not a current formal board. + +## Accessibility and Inclusion Expectations + +Contributors should consider: +- Clear, readable language. +- Keyboard usability. +- Contrast and text sizing. +- Screen reader labels and semantic structure. +- Mobile usability. +- Avoiding assumptions about geography, class, school model, or technology access. +- Respectful framing of African, African-American, Caribbean, and diaspora experiences. + +Accessibility issues should use the accessibility issue template. diff --git a/docs/github-community-setup.md b/docs/github-community-setup.md new file mode 100644 index 0000000..96c0f99 --- /dev/null +++ b/docs/github-community-setup.md @@ -0,0 +1,77 @@ +# GitHub Community Setup + +Some Phase 1 readiness items require repository owner action in GitHub settings. + +## Recommended Labels + +Core: +- `good first issue` +- `help wanted` +- `question` +- `blocked` + +Area: +- `documentation` +- `frontend` +- `backend` +- `testing` +- `demo` +- `curriculum` +- `accessibility` +- `educator feedback` +- `historical accuracy` +- `security` + +Priority: +- `priority: low` +- `priority: medium` +- `priority: high` + +Type: +- `type: bug` +- `type: feature` +- `type: chore` +- `type: docs` +- `type: review` + +Review state: +- `needs triage` +- `needs maintainer review` +- `needs educator review` +- `needs historical review` +- `needs accessibility review` + +## Good First Issue Guidance + +Good first issues should be small, well-scoped, and low-risk. + +Each issue should include: +- Context. +- Files or area likely involved. +- Expected outcome. +- Acceptance criteria. +- Validation command or review step. +- Whether screenshots are needed. + +Good first issue examples: +- Clarify a setup step. +- Fix a typo or broken link. +- Add alt text or aria labels. +- Improve issue-template wording. +- Add a small test around existing behavior. +- Document a known demo limitation. + +## GitHub Discussions Recommendation + +Enable GitHub Discussions when maintainers are ready to respond consistently. + +Suggested categories: +- Announcements: maintainer updates. +- Introductions: educators, developers, and organizers introducing themselves. +- Q&A: setup and contribution questions. +- Educator feedback: classroom, curriculum, age-fit, and facilitation discussion. +- Contributor help: technical onboarding and first PR support. +- Roadmap: public planning and prioritization. +- Show and tell: demos, screenshots, and community examples. + +Start with issues only if maintainer capacity is limited. Enable Discussions after the first small outreach cohort if issue threads become too broad. diff --git a/docs/open-source-readiness-audit.md b/docs/open-source-readiness-audit.md new file mode 100644 index 0000000..b102af2 --- /dev/null +++ b/docs/open-source-readiness-audit.md @@ -0,0 +1,35 @@ +# Open-Source Readiness Audit + +This audit records the Phase 1 baseline for `prepare-open-source-community-launch`. + +## Confirmed Project Facts + +- Live app: https://echoed-theta.vercel.app/ +- GitHub repository: https://github.com/mrwrite/echoed +- License: MIT, copyright 2025 Anthony Wright +- Current stage: pre-community-launch, no current public users or contributors +- Demo status: working K-5 demo with shared demo-only credentials +- Budget: no paid outreach budget; outreach will be organic and community-driven +- Community contact used for Phase 1 docs: `support@echoed.com` + +## Gaps Found + +- README used placeholder GitHub URLs and stale hosting references. +- README contained unreadable encoding artifacts. +- Standard community files were missing: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `ROADMAP.md`, `ARCHITECTURE.md`, and `SECURITY.md`. +- `.github/ISSUE_TEMPLATE/` existed but had no templates. +- No pull request template existed. +- Demo credentials were documented in an internal operator runbook, but public demo safety guidance was not separated. +- Contributor onboarding was too thin for a first-time external contributor. +- No documented educator review, historical accuracy review, contributor recognition, or advisory circle concept existed. +- No minimum public-facing checklist existed before outreach. +- GitHub labels and Discussions recommendations were not documented. + +## Phase 1 Decisions + +- Public demo credentials live in [public-demo.md](public-demo.md), not directly on the landing page. +- README links to the public demo guide and warns against entering real data. +- Internal demo reset and operator details remain in [demo-readiness.md](demo-readiness.md). +- Community contact remains `support@echoed.com` until a final public inbox is chosen. +- GitHub-native surfaces are the first community infrastructure: issues, pull requests, labels, and recommended Discussions categories. +- GitHub labels and Discussions are documented as owner setup steps because they require repository settings. diff --git a/docs/outreach-readiness.md b/docs/outreach-readiness.md new file mode 100644 index 0000000..1e90442 --- /dev/null +++ b/docs/outreach-readiness.md @@ -0,0 +1,122 @@ +# Outreach Readiness Guide + +EchoEd should not begin broad organic outreach until the public-facing basics are ready. + +## Minimum Viable Public-Facing Checklist + +Complete before outreach: + +- [ ] README is current, readable, and free of placeholder links. +- [ ] Public app URL is documented. +- [ ] Demo guide explains safe use, roles, credentials, limitations, and feedback paths. +- [ ] `CONTRIBUTING.md` explains setup, tests, first contribution flow, and PR expectations. +- [ ] `CODE_OF_CONDUCT.md` is present. +- [ ] `SECURITY.md` is present. +- [ ] `ROADMAP.md` is present. +- [ ] `ARCHITECTURE.md` is present. +- [ ] Issue templates exist for bugs, features, educator feedback, historical accuracy, accessibility, and good-first-issue proposals. +- [ ] Pull request template exists. +- [ ] Label recommendations are documented. +- [ ] GitHub Discussions recommendation is documented. +- [ ] Community trust guide documents educator review, historical accuracy review, recognition, advisory circle concept, accessibility, and non-extractive language. +- [ ] At least 5 small candidate issues exist or are ready to create. +- [ ] OpenSpec validation passes for the launch-readiness change. + +## Before Contacting Educators + +Complete: +- Public demo guide. +- Educator/curriculum feedback issue template. +- Historical accuracy issue template. +- Community trust guide. +- Clear statement that the project is early and no-budget. +- Bounded ask such as "review one learner flow" or "review one lesson for age fit and framing." + +## Before Contacting HBCUs + +Complete: +- README and demo guide. +- Contributor setup instructions. +- Good-first-issue structure. +- Clear asks for education faculty, CS faculty, student groups, or service-learning groups. +- A way to route both educator feedback and developer contribution interest. + +## Before Contacting Developer Groups + +Complete: +- CONTRIBUTING.md. +- ARCHITECTURE.md. +- Issue templates. +- PR template. +- Small starter issues. +- Testing instructions. +- Maintainer capacity statement. + +## Before Contacting Homeschool and Community Learning Groups + +Complete: +- Public demo guide. +- Educator-facing explanation. +- Safety warning against entering real learner data. +- Feedback path for age fit, usefulness, accessibility, and cultural framing. + +## Recommended First Outreach Targets + +Start with warm, bounded outreach rather than mass posting. + +### Black Educator Networks + +- Local Black educator associations. +- National Alliance of Black School Educators chapters. +- Black Teacher Project community contacts. +- African-American studies teacher groups. +- Black homeschool networks. + +### HBCU Programs + +- HBCU education departments. +- HBCU computer science departments. +- NSBE chapters at HBCUs. +- Student open-source clubs. +- Digital humanities or Africana studies programs. + +### Black Software Developer Communities + +- Blacks In Technology. +- Black Tech Pipeline community channels. +- Black developer Slack or Discord communities. +- Open-source maintainers focused on education, civic tech, accessibility, or developer onboarding. + +### Africa and Caribbean Contacts + +- Education technology communities. +- African history and diaspora education networks. +- Caribbean studies educators. +- University education and computer science groups. +- Community learning organizations. + +## Outreach Tracking Structure + +Use a spreadsheet with these columns: + +| Column | Purpose | +| --- | --- | +| Person or organization | Who you contacted | +| Contact name | Specific person if known | +| Region | United States, Africa, Caribbean, or other | +| Audience | Educator, developer, HBCU, organizer, student, advisor | +| Channel | Email, LinkedIn, GitHub, event, introduction | +| Ask | Demo review, intro, contribution, advisory, feedback | +| Status | Not contacted, contacted, replied, scheduled, closed | +| Next step | Concrete follow-up | +| Owner | Person responsible for follow-up | +| Outcome | Feedback, issue, contributor, advisor, no response | + +## Organic Outreach Principles + +- Lead with mission and specificity. +- Ask for one bounded action at a time. +- Do not imply the project is classroom-ready before review. +- Do not imply there is paid work if there is no budget. +- Thank people without pressuring them for more. +- Convert useful feedback into visible issues or roadmap updates. diff --git a/docs/public-demo.md b/docs/public-demo.md new file mode 100644 index 0000000..8f65f96 --- /dev/null +++ b/docs/public-demo.md @@ -0,0 +1,92 @@ +# EchoEd Public Demo Guide + +Use this guide to evaluate the public EchoEd demo. + +Live app: https://echoed-theta.vercel.app/ + +## Before You Start + +The demo is shared and resettable. Do not enter personal, student, school, or production data. + +The demo is useful for: +- Seeing the current K-5 learning experience. +- Reviewing student, teacher, and admin flows. +- Giving educator, curriculum, accessibility, or product feedback. +- Understanding where developers can contribute. + +The demo is not: +- A production school environment. +- A private workspace. +- A place to store real learner information. +- A complete statement of historical or classroom readiness. + +## Demo Credentials + +These accounts are shared, demo-only, and may be reset. + +| Role | Username | Password | What to Review | +| --- | --- | --- | --- | +| Student | `normalstudent` | `password` | Learner dashboard, course access, lesson flow | +| Teacher | `teacher` | `password` | Educator dashboard and learner visibility | +| Admin | `orgadmin` | `password` | Organization-level surfaces | +| Content admin | `contentadmin` | `password` | Workspace and content/admin surfaces | + +Additional deterministic learner states may exist for internal review: + +| Username | Password | Expected State | +| --- | --- | --- | +| `masteredstudent` | `password` | Enrichment | +| `reteachstudent` | `password` | Reteach | +| `reviewstudent` | `password` | Review | +| `monitorstudent` | `password` | Monitor | + +## Suggested Educator Walkthrough + +1. Open https://echoed-theta.vercel.app/. +2. Select `Try demo`. +3. Sign in as `normalstudent`. +4. Review the student dashboard, course access, lesson entry, activity flow, language, age fit, and clarity. +5. Sign out and sign in as `teacher`. +6. Review whether the teacher view gives enough context to support learners. +7. File feedback using the educator/curriculum feedback issue template. + +Useful educator feedback: +- Grade or learner context. +- What felt useful. +- What felt unclear or inaccessible. +- Historical, cultural, or source concerns. +- Suggested discussion prompts or classroom supports. +- What would be required before classroom use. + +## Suggested Developer Walkthrough + +1. Open the live app and try the student flow. +2. Read [../ARCHITECTURE.md](../ARCHITECTURE.md). +3. Read [../CONTRIBUTING.md](../CONTRIBUTING.md). +4. Run the app locally if you want to contribute. +5. File setup friction, accessibility, docs, frontend, backend, or testing issues. + +## Suggested Community Organizer Walkthrough + +1. Read the landing page and README. +2. Try the student demo. +3. Review [community-trust.md](community-trust.md). +4. Note what would make the project easier to share with educators, HBCUs, homeschool groups, or developer networks. +5. Use GitHub issues or `support@echoed.com` for introductions or feedback. + +## Feedback Paths + +- Bugs: GitHub bug report template. +- Educator review: educator/curriculum feedback template. +- Historical accuracy or source concern: historical accuracy issue template. +- Accessibility concern: accessibility issue template. +- Security concern: [../SECURITY.md](../SECURITY.md). +- General contact: `support@echoed.com`. + +## Known Limitations + +- The project is early and pre-community-launch. +- Demo data is shared and may change. +- The public app is temporarily hosted at `echoed-theta.vercel.app`. +- AI generation, payments, marketplace, subscriptions, and production onboarding are not Phase 1 goals. +- Some internal demo operation details live in [demo-readiness.md](demo-readiness.md) and are intended for maintainers. diff --git a/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/.openspec.yaml b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/.openspec.yaml new file mode 100644 index 0000000..074342d --- /dev/null +++ b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-07-09 diff --git a/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/design.md b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/design.md new file mode 100644 index 0000000..ba72448 --- /dev/null +++ b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/design.md @@ -0,0 +1,107 @@ +## Context + +EchoEd is a full-stack Angular and FastAPI education platform centered on African and African-American history. The repository already contains a working application, deterministic demo runbooks, OpenSpec workflow, CI configuration, and an MIT license, but the public-facing repository is not yet ready for community outreach: + +- `README.md` contains stale placeholder GitHub URLs, outdated hosting references, and encoding artifacts. +- Standard community files such as `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `ROADMAP.md`, `ARCHITECTURE.md`, and `SECURITY.md` are absent. +- `.github/ISSUE_TEMPLATE/` exists but is empty, and there is no pull request template. +- Demo runbooks exist, but public demo guidance and shared-credential handling need to be separated from internal operator instructions. +- The landing page now speaks to educators and developers, but it still needs aligned public demo instructions, screenshots or walkthrough guidance, and contribution pathways before major outreach. +- The project has no current users, contributors, advisors, stars, or community traction, so first impressions matter. + +Phase 1 is a public-readiness phase, not a feature-building phase. The intended stakeholders are educators, African-American studies teachers, homeschool and community learning organizers, Black software developers, HBCU programs, potential advisors, and first-time open-source contributors across the United States, Africa, and the Caribbean. + +## Goals / Non-Goals + +**Goals:** + +- Make the repository understandable within a few minutes for educators and developers. +- Make the project contributor-ready with clear setup, testing, issue, PR, and communication guidance. +- Make the live demo safe and useful for public visitors without exposing confusing internal operations. +- Establish trust practices for historical accuracy, educator review, accessibility, inclusion, recognition, and non-extractive participation. +- Define the minimum viable public-facing checklist that must be complete before broad organic outreach begins. +- Recommend first outreach targets after Phase 1 is complete. + +**Non-Goals:** + +- No new application runtime features. +- No backend API changes. +- No database, migration, or authentication changes. +- No paid marketing, ads, sponsorships, or paid tooling. +- No formal nonprofit, advisory board, fiscal sponsorship, or governance entity setup. +- No requirement to support production user onboarding beyond the current public demo and contribution flow. + +## Decisions + +### Decision: Treat Phase 1 as a readiness gate, not outreach itself + +Phase 1 will produce documentation, templates, demo guidance, and trust processes. Outreach to educators, HBCUs, developer groups, and community organizers begins only after a minimum viable checklist passes. + +Alternatives considered: + +- Start outreach immediately and improve docs reactively. Rejected because early visitors would encounter placeholder links, missing contribution guidance, and unclear demo instructions. +- Build more product features first. Rejected because the current blocker is trust and clarity, not feature depth. + +### Decision: Separate internal demo operations from public demo guidance + +Existing demo runbooks can remain operator-focused. Public-facing README and landing content should present a safe, concise demo path: what the demo shows, who should try it, how credentials are handled, what limitations exist, and how to report feedback. + +Alternatives considered: + +- Publish all internal runbook details as the primary demo path. Rejected because it overwhelms non-technical visitors and can normalize shared credentials without context. +- Remove demo credentials entirely. Rejected for Phase 1 because the current no-budget outreach plan needs low-friction evaluation. + +### Decision: Use GitHub-native community infrastructure first + +Phase 1 will use repository files, GitHub issue templates, PR templates, labels, and a recommendation to enable GitHub Discussions. This avoids new infrastructure while the project has no traction and no budget. + +Alternatives considered: + +- Create a separate Discord, Slack, CRM, or custom community portal now. Rejected because each adds moderation and maintenance overhead before there is a community. +- Use email only. Rejected because developer contributors need transparent issue and discussion history. + +### Decision: Define educator participation without extractive framing + +Educator review requests must be specific, bounded, credited when desired, and clear about the current no-budget status. The project must not frame open-ended curriculum labor as casual feedback. + +Alternatives considered: + +- Ask broadly for "educator feedback" without structure. Rejected because it is vague and can feel extractive. +- Delay educator review until funding exists. Rejected because early educator judgment is essential to mission fit; Phase 1 can still define respectful, bounded participation. + +### Decision: Create one new OpenSpec capability for community readiness + +The requirements cut across docs, GitHub configuration, landing content, and community process. A new `open-source-community-readiness` capability keeps these requirements separate from runtime product specs. + +Alternatives considered: + +- Modify landing-page or demo-readiness specs only. Rejected because repository trust, contributor onboarding, community review, and outreach readiness are broader than landing/demo behavior. + +## Risks / Trade-offs + +- [Risk] Shared demo credentials may be misused after public outreach. -> Mitigation: document credential scope, reset expectations, limitations, and owner monitoring; keep credentials demo-only and separate from real user data. +- [Risk] Community docs can overpromise governance or support capacity. -> Mitigation: state the project stage plainly and distinguish current practices from future aspirations. +- [Risk] Educator and historical accuracy review may appear performative without visible process. -> Mitigation: add an explicit review pathway, issue template, recognition option, and advisory circle concept. +- [Risk] First contributors may still struggle with local setup. -> Mitigation: include verified setup commands, env variable guidance, seed data instructions, and testing commands in `CONTRIBUTING.md` and `ARCHITECTURE.md`. +- [Risk] GitHub Discussions and labels require manual repository settings. -> Mitigation: document owner-only setup steps and keep codebase deliverables useful even if settings are enabled later. +- [Risk] The README may become too long for non-technical educators. -> Mitigation: structure README with a concise mission, demo, educator path, developer path, and links to deeper docs. +- [Risk] No paid budget limits reach and response speed. -> Mitigation: prioritize warm, specific, organic outreach targets after readiness is complete. + +## Migration Plan + +1. Add repository community files and templates without changing application code. +2. Refresh README and supporting docs to point to the real repository, temporary live app, public demo path, and current project status. +3. Add or update landing/demo copy only where needed to align with the public docs. +4. Add issue and PR templates, plus a labels recommendation document because labels may need manual GitHub setup. +5. Run markdown review, link review, OpenSpec validation, and existing build/test smoke checks appropriate for docs-only changes. +6. Enable GitHub Discussions manually after docs are merged, if the repository owner agrees. + +Rollback is straightforward: revert the documentation/template changes. No database, API, or runtime migration is involved. + +## Open Questions + +- What public email address should be used for community inquiries if `support@echoed.com` is not final? +- Should shared demo credentials remain in the README, live landing page, a separate demo guide, or only behind a request flow? +- Which contributor recognition format is preferred: README acknowledgements, release notes, contributor profile page, or all of these? +- Who is the first named maintainer responsible for triage, code review, educator review routing, and security reports? +- Should GitHub Discussions be enabled immediately after Phase 1 or after the first small outreach cohort? diff --git a/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/proposal.md b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/proposal.md new file mode 100644 index 0000000..2e709db --- /dev/null +++ b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/proposal.md @@ -0,0 +1,34 @@ +## Why + +EchoEd wants to begin organic outreach to Black educators, African-American history educators, Black software developers, HBCU communities, and education organizers across the United States, Africa, and the Caribbean. Before that outreach starts, the public repository and live demo need to be trustworthy, understandable, and contributor-ready so early visitors know what EchoEd is, how to evaluate it, and how to help without being asked for unclear unpaid labor. + +## What Changes + +- Define Phase 1 as a documentation, trust, onboarding, and public-demo readiness effort. +- Improve the repository front door with a refreshed README, verified MIT license references, clear status, public demo guidance, project structure, and contribution pathways. +- Add standard community files: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `ROADMAP.md`, `ARCHITECTURE.md`, and `SECURITY.md`. +- Add GitHub issue templates, a pull request template, recommended labels, good-first-issue guidance, and a GitHub Discussions recommendation. +- Clarify local development setup, environment variables, seed/demo data, testing commands, first contribution steps, and communication norms. +- Establish community trust guidance: non-extractive language, educator review process, contributor recognition, advisory circle concept, historical accuracy review, accessibility expectations, and inclusion expectations. +- Make the landing/demo path public-ready with mission language, demo instructions, safe handling of shared credentials, screenshots or walkthrough guidance, educator-facing explanation, developer-facing explanation, and community contribution pathways. +- Define the minimum viable checklist that must be complete before contacting educators, HBCUs, developer groups, and community organizers. +- Identify recommended first outreach targets after Phase 1, while keeping outreach organic and no-budget. +- No product runtime, API, data model, authentication, or deployment behavior changes are included in this phase. + +## Capabilities + +### New Capabilities + +- `open-source-community-readiness`: Defines the public repository, demo, contributor onboarding, trust, and outreach-readiness requirements EchoEd must satisfy before major open-source community outreach begins. + +### Modified Capabilities + +- None. + +## Impact + +- Affected repository files: root README, community documentation, GitHub templates, and supporting docs. +- Affected frontend/public messaging: landing-page copy and demo instructions only; no route or runtime behavior changes are planned. +- Affected operations: demo credential handling guidance, public walkthrough guidance, and pre-outreach checklist. +- Affected community process: issue labels, good-first-issue structure, contributor recognition, educator review process, advisory circle concept, and discussion-channel recommendation. +- Dependencies: GitHub repository settings for labels and Discussions may require manual owner action outside the codebase. diff --git a/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/specs/open-source-community-readiness/spec.md b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/specs/open-source-community-readiness/spec.md new file mode 100644 index 0000000..36991ad --- /dev/null +++ b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/specs/open-source-community-readiness/spec.md @@ -0,0 +1,100 @@ +## ADDED Requirements + +### Requirement: Repository Readiness +EchoEd SHALL provide a trustworthy public repository front door before major outreach begins. + +#### Scenario: Required community files exist +- **WHEN** Phase 1 repository readiness is complete +- **THEN** the repository contains an updated `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `ROADMAP.md`, `ARCHITECTURE.md`, `SECURITY.md`, and verified `LICENSE` references + +#### Scenario: README explains the project clearly +- **WHEN** a first-time visitor opens the README +- **THEN** the README explains EchoEd's mission, current stage, live app URL, demo availability, educator path, developer path, contribution path, project structure, setup summary, license, and contact path without placeholder repository links or mojibake text + +#### Scenario: GitHub contribution surfaces are ready +- **WHEN** a visitor wants to report, review, or contribute +- **THEN** the repository provides GitHub issue templates, a pull request template, a good-first-issue structure, and label recommendations for maintainer setup + +#### Scenario: Discussions recommendation is documented +- **WHEN** repository owner setup tasks are reviewed +- **THEN** the Phase 1 materials recommend whether and how to enable GitHub Discussions for Q&A, educator feedback, contributor introductions, and roadmap discussion + +### Requirement: Landing and Demo Readiness +EchoEd SHALL present a public landing and demo path that is understandable, safe, and aligned with community outreach. + +#### Scenario: Landing page states mission and audiences +- **WHEN** a public visitor opens the live app landing page +- **THEN** the page presents a clear mission statement and separate educator-facing, developer-facing, and community contribution pathways + +#### Scenario: Public demo instructions are clear +- **WHEN** a visitor wants to try the demo +- **THEN** the public documentation explains what the K-5 demo includes, what roles are available, how to access demo credentials, what data is safe to enter, and what limitations apply + +#### Scenario: Demo credentials are handled safely +- **WHEN** shared demo credentials are documented or linked +- **THEN** they are clearly marked as demo-only, bounded to non-sensitive use, resettable, and not appropriate for personal, student, school, or production data + +#### Scenario: Walkthrough guidance supports evaluation +- **WHEN** an educator, developer, or organizer evaluates EchoEd +- **THEN** they can follow screenshots, a short walkthrough, or a concise demo guide that explains what to look at and how to send feedback + +### Requirement: Contributor Onboarding +EchoEd SHALL enable a new contributor to understand the project and attempt a first contribution without private maintainer context. + +#### Scenario: Local setup is documented +- **WHEN** a developer follows `CONTRIBUTING.md` +- **THEN** they can find frontend setup, backend setup, environment variable guidance, database/migration guidance, seed or demo data instructions, and expected local URLs + +#### Scenario: Testing instructions are documented +- **WHEN** a contributor prepares a pull request +- **THEN** they can find backend test commands, frontend test commands, build commands, demo smoke guidance where relevant, and instructions for reporting tests they could not run + +#### Scenario: Project structure is understandable +- **WHEN** a new contributor reads `ARCHITECTURE.md` +- **THEN** they can identify the Angular frontend, FastAPI backend, database/migration layer, demo seed system, OpenSpec workflow, and primary ownership boundaries without reading the whole codebase first + +#### Scenario: First contribution path is bounded +- **WHEN** a first-time contributor wants to help +- **THEN** the repository points them to small issues, expected workflow, branch and PR expectations, review norms, communication guidelines, and examples of educator-review, docs, frontend, backend, testing, accessibility, and curriculum-tooling contributions + +### Requirement: Community Trust Practices +EchoEd SHALL describe community practices that make educator and contributor participation respectful, bounded, and mission-aligned. + +#### Scenario: Non-extractive language is used +- **WHEN** public docs ask educators, reviewers, or community members for help +- **THEN** the ask is specific, bounded, transparent about the no-budget stage, and clear about how input may be used and recognized + +#### Scenario: Educator review process is defined +- **WHEN** an educator wants to review EchoEd +- **THEN** the repository explains how to review lessons or demo flows, how to file feedback, what kind of feedback is useful, and how review input is triaged + +#### Scenario: Historical accuracy review is defined +- **WHEN** historical content, curriculum framing, or source quality is questioned +- **THEN** the repository provides a documented path for historical accuracy review, source concerns, cultural framing concerns, and resolution tracking + +#### Scenario: Recognition and advisory concepts are documented +- **WHEN** contributors, educators, or advisors provide meaningful help +- **THEN** the repository explains available recognition options and describes the advisory circle concept without implying a formal board exists before it does + +#### Scenario: Accessibility and inclusion expectations are explicit +- **WHEN** a contributor changes public docs, UI, demo flows, or learning content +- **THEN** Phase 1 guidance requires accessibility, inclusive language, readable communication, and culturally respectful review expectations + +### Requirement: Outreach Readiness Gate +EchoEd SHALL define what must be complete before broad organic outreach begins. + +#### Scenario: Minimum viable public-facing checklist exists +- **WHEN** Phase 1 is ready for implementation review +- **THEN** the change includes a checklist covering repository docs, templates, demo instructions, landing clarity, good-first issues, communication paths, trust practices, and validation steps + +#### Scenario: Outreach does not start before readiness criteria pass +- **WHEN** maintainers plan to contact educators, HBCUs, developer groups, or community organizers +- **THEN** they can verify that the minimum viable checklist is complete and that unresolved gaps are documented + +#### Scenario: First outreach targets are recommended +- **WHEN** Phase 1 readiness is complete +- **THEN** maintainers have a practical first-target list for organic outreach, including Black educator networks, African-American studies educators, HBCU education and CS programs, Black software developer groups, homeschool and community learning groups, and Africa or Caribbean education technology contacts + +#### Scenario: Validation is defined +- **WHEN** Phase 1 implementation is complete +- **THEN** maintainers can run OpenSpec validation and appropriate docs, link, build, and smoke checks to confirm readiness without requiring new paid services diff --git a/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/tasks.md b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/tasks.md new file mode 100644 index 0000000..3290101 --- /dev/null +++ b/openspec/changes/archive/2026-07-09-prepare-open-source-community-launch/tasks.md @@ -0,0 +1,62 @@ +## 1. Baseline Audit and Decisions + +- [x] 1.1 Record the current repository readiness gaps: stale README links, missing community files, empty issue template folder, missing PR template, demo credential exposure, and missing contributor onboarding. +- [x] 1.2 Confirm the public project facts to publish: live app URL, GitHub URL, temporary hosting status, project stage, current maintainer contact, and current demo availability. +- [x] 1.3 Decide where public demo credentials will live: README, dedicated demo guide, landing page, or request-only flow. +- [x] 1.4 Decide the initial community contact path and replace any placeholder contact or social links. + +## 2. Repository Readiness + +- [x] 2.1 Rewrite `README.md` with mission, current status, live app, demo path, educator path, developer path, community path, project structure, setup summary, testing summary, license, and contact information. +- [x] 2.2 Remove placeholder GitHub URLs, stale hosting references, and mojibake/encoding artifacts from the README. +- [x] 2.3 Verify `LICENSE` is MIT and referenced accurately from README and contribution docs. +- [x] 2.4 Add `ROADMAP.md` with practical near-term milestones, including Phase 1 readiness, early educator review, contributor onboarding, and later product/runtime priorities. +- [x] 2.5 Add `ARCHITECTURE.md` summarizing frontend, backend, database, migrations, demo seed, OpenSpec workflow, and key code ownership boundaries. +- [x] 2.6 Add `SECURITY.md` with vulnerability reporting, supported scope, demo credential cautions, and sensitive-data handling expectations. + +## 3. Contributor Onboarding + +- [x] 3.1 Add `CONTRIBUTING.md` with first contribution workflow, local frontend setup, local backend setup, environment variables, migrations, seed/demo data, testing commands, and PR expectations. +- [x] 3.2 Document how contributors should report tests they could not run. +- [x] 3.3 Add first-contribution guidance for documentation, educator review, frontend, backend, tests, accessibility, and curriculum tooling. +- [x] 3.4 Add communication guidelines covering respectful discussion, review expectations, maintainer response limitations, and no-budget project stage. +- [x] 3.5 Add good-first-issue guidance with example issue shapes and acceptance criteria for small starter tasks. + +## 4. GitHub Community Surfaces + +- [x] 4.1 Add issue templates for bug report, feature request, educator/curriculum feedback, historical accuracy or source concern, accessibility issue, and good-first-issue proposal. +- [x] 4.2 Add `.github/pull_request_template.md` with summary, motivation, test plan, screenshots when relevant, accessibility check, and community/curriculum impact check. +- [x] 4.3 Add a labels recommendation document covering `good first issue`, `help wanted`, `educator feedback`, `historical accuracy`, `accessibility`, `documentation`, `frontend`, `backend`, `testing`, `demo`, `curriculum`, `question`, `blocked`, and priority labels. +- [x] 4.4 Add a GitHub Discussions recommendation with suggested categories for introductions, Q&A, educator feedback, contributor help, roadmap, and show-and-tell. + +## 5. Landing and Demo Readiness + +- [x] 5.1 Review the landing page against the Phase 1 mission and ensure it clearly routes visitors to educator, developer, demo, and community contribution paths. +- [x] 5.2 Add public demo instructions that explain demo roles, access steps, safe use, reset expectations, limitations, and feedback paths. +- [x] 5.3 Ensure demo credential handling is clearly marked as demo-only and excludes personal, student, school, or production data. +- [x] 5.4 Add screenshot or walkthrough guidance for educators, developers, and community organizers evaluating the K-5 demo. +- [x] 5.5 Link the README, landing page, demo guidance, and GitHub contribution paths consistently. + +## 6. Community Trust Process + +- [x] 6.1 Add `CODE_OF_CONDUCT.md` with inclusive, respectful participation expectations and enforcement contact guidance. +- [x] 6.2 Add non-extractive language guidance for educator asks, including bounded review requests and transparency about the no-budget stage. +- [x] 6.3 Document the educator review process, including what to review, how to submit feedback, how feedback is triaged, and how reviewers can be recognized. +- [x] 6.4 Document the historical accuracy review process for source concerns, framing concerns, curriculum corrections, and resolution tracking. +- [x] 6.5 Document contributor recognition options and the advisory circle concept without implying a formal board already exists. +- [x] 6.6 Document accessibility and inclusion expectations for docs, UI, demo flows, and learning content. + +## 7. Outreach Readiness + +- [x] 7.1 Create a minimum viable public-facing checklist that must pass before outreach begins. +- [x] 7.2 Define what must be complete before contacting educators, HBCUs, developer groups, homeschool groups, and community organizers. +- [x] 7.3 Add recommended first outreach targets after Phase 1, grouped by Black educator networks, African-American studies educators, HBCU education and CS programs, Black software developer communities, homeschool/community learning groups, and Africa or Caribbean education technology contacts. +- [x] 7.4 Add a simple outreach tracking structure with fields for person or organization, contact, region, audience, channel, status, next step, owner, and outcome. + +## 8. Validation + +- [x] 8.1 Run `openspec validate prepare-open-source-community-launch --strict`. +- [x] 8.2 Review all new Markdown files for broken relative links, placeholder links, stale project facts, and unreadable encoding artifacts. +- [x] 8.3 Run the frontend build if landing copy or routing changes are made. +- [x] 8.4 Run targeted demo smoke or manual demo walkthrough checks if public demo instructions change. +- [x] 8.5 Confirm no application runtime, API, database, authentication, or migration behavior changed as part of Phase 1. diff --git a/openspec/specs/open-source-community-readiness/spec.md b/openspec/specs/open-source-community-readiness/spec.md new file mode 100644 index 0000000..8559ce6 --- /dev/null +++ b/openspec/specs/open-source-community-readiness/spec.md @@ -0,0 +1,106 @@ +# Open Source Community Readiness Specification + +## Purpose + +Define the repository, demo, contributor onboarding, community trust, and outreach-readiness requirements EchoEd must satisfy before broad public open-source outreach. + +## Requirements + +### Requirement: Repository Readiness +EchoEd SHALL provide a trustworthy public repository front door before major outreach begins. + +#### Scenario: Required community files exist +- **WHEN** Phase 1 repository readiness is complete +- **THEN** the repository contains an updated `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `ROADMAP.md`, `ARCHITECTURE.md`, `SECURITY.md`, and verified `LICENSE` references + +#### Scenario: README explains the project clearly +- **WHEN** a first-time visitor opens the README +- **THEN** the README explains EchoEd's mission, current stage, live app URL, demo availability, educator path, developer path, contribution path, project structure, setup summary, license, and contact path without placeholder repository links or mojibake text + +#### Scenario: GitHub contribution surfaces are ready +- **WHEN** a visitor wants to report, review, or contribute +- **THEN** the repository provides GitHub issue templates, a pull request template, a good-first-issue structure, and label recommendations for maintainer setup + +#### Scenario: Discussions recommendation is documented +- **WHEN** repository owner setup tasks are reviewed +- **THEN** the Phase 1 materials recommend whether and how to enable GitHub Discussions for Q&A, educator feedback, contributor introductions, and roadmap discussion + +### Requirement: Landing and Demo Readiness +EchoEd SHALL present a public landing and demo path that is understandable, safe, and aligned with community outreach. + +#### Scenario: Landing page states mission and audiences +- **WHEN** a public visitor opens the live app landing page +- **THEN** the page presents a clear mission statement and separate educator-facing, developer-facing, and community contribution pathways + +#### Scenario: Public demo instructions are clear +- **WHEN** a visitor wants to try the demo +- **THEN** the public documentation explains what the K-5 demo includes, what roles are available, how to access demo credentials, what data is safe to enter, and what limitations apply + +#### Scenario: Demo credentials are handled safely +- **WHEN** shared demo credentials are documented or linked +- **THEN** they are clearly marked as demo-only, bounded to non-sensitive use, resettable, and not appropriate for personal, student, school, or production data + +#### Scenario: Walkthrough guidance supports evaluation +- **WHEN** an educator, developer, or organizer evaluates EchoEd +- **THEN** they can follow screenshots, a short walkthrough, or a concise demo guide that explains what to look at and how to send feedback + +### Requirement: Contributor Onboarding +EchoEd SHALL enable a new contributor to understand the project and attempt a first contribution without private maintainer context. + +#### Scenario: Local setup is documented +- **WHEN** a developer follows `CONTRIBUTING.md` +- **THEN** they can find frontend setup, backend setup, environment variable guidance, database/migration guidance, seed or demo data instructions, and expected local URLs + +#### Scenario: Testing instructions are documented +- **WHEN** a contributor prepares a pull request +- **THEN** they can find backend test commands, frontend test commands, build commands, demo smoke guidance where relevant, and instructions for reporting tests they could not run + +#### Scenario: Project structure is understandable +- **WHEN** a new contributor reads `ARCHITECTURE.md` +- **THEN** they can identify the Angular frontend, FastAPI backend, database/migration layer, demo seed system, OpenSpec workflow, and primary ownership boundaries without reading the whole codebase first + +#### Scenario: First contribution path is bounded +- **WHEN** a first-time contributor wants to help +- **THEN** the repository points them to small issues, expected workflow, branch and PR expectations, review norms, communication guidelines, and examples of educator-review, docs, frontend, backend, testing, accessibility, and curriculum-tooling contributions + +### Requirement: Community Trust Practices +EchoEd SHALL describe community practices that make educator and contributor participation respectful, bounded, and mission-aligned. + +#### Scenario: Non-extractive language is used +- **WHEN** public docs ask educators, reviewers, or community members for help +- **THEN** the ask is specific, bounded, transparent about the no-budget stage, and clear about how input may be used and recognized + +#### Scenario: Educator review process is defined +- **WHEN** an educator wants to review EchoEd +- **THEN** the repository explains how to review lessons or demo flows, how to file feedback, what kind of feedback is useful, and how review input is triaged + +#### Scenario: Historical accuracy review is defined +- **WHEN** historical content, curriculum framing, or source quality is questioned +- **THEN** the repository provides a documented path for historical accuracy review, source concerns, cultural framing concerns, and resolution tracking + +#### Scenario: Recognition and advisory concepts are documented +- **WHEN** contributors, educators, or advisors provide meaningful help +- **THEN** the repository explains available recognition options and describes the advisory circle concept without implying a formal board exists before it does + +#### Scenario: Accessibility and inclusion expectations are explicit +- **WHEN** a contributor changes public docs, UI, demo flows, or learning content +- **THEN** Phase 1 guidance requires accessibility, inclusive language, readable communication, and culturally respectful review expectations + +### Requirement: Outreach Readiness Gate +EchoEd SHALL define what must be complete before broad organic outreach begins. + +#### Scenario: Minimum viable public-facing checklist exists +- **WHEN** Phase 1 is ready for implementation review +- **THEN** the change includes a checklist covering repository docs, templates, demo instructions, landing clarity, good-first issues, communication paths, trust practices, and validation steps + +#### Scenario: Outreach does not start before readiness criteria pass +- **WHEN** maintainers plan to contact educators, HBCUs, developer groups, or community organizers +- **THEN** they can verify that the minimum viable checklist is complete and that unresolved gaps are documented + +#### Scenario: First outreach targets are recommended +- **WHEN** Phase 1 readiness is complete +- **THEN** maintainers have a practical first-target list for organic outreach, including Black educator networks, African-American studies educators, HBCU education and CS programs, Black software developer groups, homeschool and community learning groups, and Africa or Caribbean education technology contacts + +#### Scenario: Validation is defined +- **WHEN** Phase 1 implementation is complete +- **THEN** maintainers can run OpenSpec validation and appropriate docs, link, build, and smoke checks to confirm readiness without requiring new paid services