From 706922738d06b795d34fed2dfd105faa465fb584 Mon Sep 17 00:00:00 2001 From: Thomas Date: Sun, 10 May 2026 16:06:45 +0800 Subject: [PATCH] DOCS: add growth readiness assets --- .github/ISSUE_TEMPLATE/bug_report.yml | 58 +++++++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/feature_request.yml | 43 +++++ .github/ISSUE_TEMPLATE/learning_feedback.yml | 47 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 45 +++++ CONTRIBUTING.md | 72 ++++++++ README.en.md | 12 +- README.md | 12 +- SECURITY.md | 32 ++++ docs/growth-playbook.md | 168 +++++++++++++++++++ docs/launch-copy.md | 150 +++++++++++++++++ docs/privacy-and-data.md | 62 +++++++ docs/star-growth-log.md | 47 ++++++ 13 files changed, 751 insertions(+), 2 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/learning_feedback.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 docs/growth-playbook.md create mode 100644 docs/launch-copy.md create mode 100644 docs/privacy-and-data.md create mode 100644 docs/star-growth-log.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..c11473bf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,58 @@ +name: Bug report +description: Report a reproducible problem in Echo Loop. +title: "FIX: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a problem. Please avoid attaching private learning materials unless you have permission to share them. + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What did you expect Echo Loop to do? + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happened instead? + validations: + required: true + - type: textarea + id: steps + attributes: + label: Reproduction steps + description: List the smallest steps needed to reproduce the issue. + placeholder: | + 1. Import ... + 2. Tap ... + 3. See ... + validations: + required: true + - type: dropdown + id: platform + attributes: + label: Platform + options: + - iOS + - Android + - macOS + - Windows + - Linux + - Other + validations: + required: true + - type: input + id: version + attributes: + label: App version + placeholder: "Example: 1.0.10" + - type: textarea + id: logs + attributes: + label: Screenshots or logs + description: Add screenshots, screen recordings, or logs if they help explain the problem. + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..d28ef04f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Echo Loop GitHub Discussions + url: https://github.com/echo-loop/Echo-Loop/discussions + about: Use discussions for open-ended product ideas, learning methods, and community questions. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..fdbaf38f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,43 @@ +name: Feature request +description: Suggest a product or developer-facing improvement. +title: "FEAT: " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What learner, teacher, or developer problem would this solve? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the smallest useful version of the feature. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: What workaround or simpler option did you consider? + - type: dropdown + id: area + attributes: + label: Area + options: + - Learning flow + - Audio import + - Subtitles + - Shadowing evaluation + - Review scheduling + - Flashcards + - AI features + - Platform support + - Developer experience + - Documentation + - Other + validations: + required: true + diff --git a/.github/ISSUE_TEMPLATE/learning_feedback.yml b/.github/ISSUE_TEMPLATE/learning_feedback.yml new file mode 100644 index 00000000..5c9a7836 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/learning_feedback.yml @@ -0,0 +1,47 @@ +name: Learning-flow feedback +description: Share feedback after trying one real practice session. +title: "FEEDBACK: " +labels: ["feedback"] +body: + - type: markdown + attributes: + value: | + This template is for feedback after trying Echo Loop with a real audio clip. Concrete friction is more useful than general praise. + - type: textarea + id: material + attributes: + label: Practice material + description: What kind of audio did you try? Do not share private content. + placeholder: "Example: 3-minute podcast clip, interview audio, course listening material" + validations: + required: true + - type: checkboxes + id: steps + attributes: + label: Steps you tried + options: + - label: Blind listening + - label: Intensive listening + - label: Shadowing + - label: Retelling + - label: Spaced review + - label: Hard-sentence review + - label: Flashcards + - type: textarea + id: friction + attributes: + label: Biggest friction + description: Where did the workflow feel confusing, slow, or too heavy? + validations: + required: true + - type: textarea + id: value + attributes: + label: Most useful part + description: Which step made the practice better than your normal method? + - type: textarea + id: retention + attributes: + label: Would you use it again? + description: What would make you open Echo Loop again tomorrow? + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..60b1d366 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,45 @@ +## Summary + +- + +## Type + +- [ ] Bug fix +- [ ] Feature +- [ ] Documentation +- [ ] Refactor / maintenance +- [ ] Test-only change +- [ ] Release / CI + +## Checks + +- [ ] `dart format .` +- [ ] `flutter analyze` +- [ ] `flutter test` +- [ ] Not run because this is a docs-only change + +## Manual testing + +Platform tested: + +- [ ] iOS +- [ ] Android +- [ ] macOS +- [ ] Windows +- [ ] Linux +- [ ] Not applicable + +Notes: + +- + +## Data and privacy impact + +- [ ] No data/privacy impact +- [ ] Touches local audio, subtitles, transcripts, recordings, or learning records +- [ ] Touches AI/network requests +- [ ] Touches analytics, identifiers, consent, or session replay +- [ ] Touches import/export/backup/delete behavior + +If any box except "No data/privacy impact" is checked, explain the user-visible behavior and whether docs or privacy policy updates are needed. + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..cce12e20 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +# Contributing to Echo Loop + +Thanks for helping improve Echo Loop. This project is an English listening and speaking trainer built around one complete practice loop: blind listening, intensive listening, shadowing, retelling, and spaced review. + +## Good first contributions + +- Fix a bug that affects importing audio, subtitles, playback, review scheduling, or speech practice. +- Improve Chinese or English copy in the app and README. +- Add focused tests for learning flow, review reminders, subtitle parsing, ASR settings, or import edge cases. +- Improve Android, iOS, macOS, Windows, or Linux compatibility. +- Improve documentation for setup, release, privacy, or troubleshooting. + +## Before opening an issue + +Please include: + +- What you expected to happen. +- What actually happened. +- Your platform and app version. +- Reproduction steps, preferably with a small sample file if the issue involves audio or subtitles. +- Screenshots or logs when they help explain the problem. + +Do not attach private learning materials unless you have permission to share them. + +## Development setup + +```bash +git clone git@github.com:echo-loop/Echo-Loop.git +cd Echo-Loop +flutter pub get +dart run build_runner build +flutter run -d +``` + +## Quality checks + +Run these before submitting a pull request: + +```bash +dart format . +flutter analyze +flutter test +``` + +If you only changed documentation, mention that no app tests were run because the change is docs-only. + +## Pull request checklist + +- Keep the change focused on one problem. +- Add or update tests when behavior changes. +- Update README or docs when user-facing behavior changes. +- Keep generated files in sync after Riverpod, Drift, or localization changes. +- Explain manual testing for platform-specific changes. + +## Commit style + +Use the repository's existing prefix style: + +```text +FEAT: add focused review entry point +FIX: handle empty subtitle import +DOCS: clarify Android APK install path +TEST: cover review schedule boundaries +CHORE: update release script comments +``` + +Common prefixes include `FEAT`, `FIX`, `DOCS`, `MOD`, `OPT`, `CHORE`, `CI`, `RELEASE`, and `TEST`. + +## Community standards + +Be respectful, specific, and practical. Assume maintainers and contributors are working with limited time. Avoid personal attacks, harassment, spam, and low-effort promotion. + diff --git a/README.en.md b/README.en.md index 9e71803d..0de6b907 100644 --- a/README.en.md +++ b/README.en.md @@ -173,6 +173,16 @@ Practice English alongside other committed learners: share methods, give feedbac --- +## 🤝 Get involved + +- Share learning-flow feedback with the [Learning-flow feedback](https://github.com/echo-loop/Echo-Loop/issues/new?template=learning_feedback.yml) template. +- Report bugs or request features in [Issues](https://github.com/echo-loop/Echo-Loop/issues). +- Read [CONTRIBUTING.md](./CONTRIBUTING.md) before contributing code or docs. +- Report security or privacy issues privately through [SECURITY.md](./SECURITY.md). +- See [docs/privacy-and-data.md](./docs/privacy-and-data.md) for data-sensitive behavior notes. + +--- + ## 🗺️ Roadmap ### ✅ 1 · Core features @@ -253,7 +263,7 @@ flutter analyze flutter test ``` -Commit titles follow the `PREFIX: content` format (check `git log` for common prefixes — FEAT / FIX / DOCS / MOD / OPT / CHORE / CI / RELEASE, etc.). A detailed contribution guide will live in [CONTRIBUTING.md](#) (TBD). This project follows the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct. +Commit titles follow the `PREFIX: content` format (check `git log` for common prefixes — FEAT / FIX / DOCS / MOD / OPT / CHORE / CI / RELEASE, etc.). See [CONTRIBUTING.md](./CONTRIBUTING.md) for the detailed contribution guide. This project follows the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct. diff --git a/README.md b/README.md index 33093f28..edfa83f0 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,16 @@ flowchart LR --- +## 🤝 参与项目 + +- 反馈学习流程：请使用 [Learning-flow feedback](https://github.com/echo-loop/Echo-Loop/issues/new?template=learning_feedback.yml) 模板，告诉我们哪一步最卡。 +- 报告 Bug 或提功能建议：请到 [Issues](https://github.com/echo-loop/Echo-Loop/issues)。 +- 贡献代码或文档：请先阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。 +- 安全或隐私问题：请按 [SECURITY.md](./SECURITY.md) 私下报告。 +- 数据与隐私说明：见 [docs/privacy-and-data.md](./docs/privacy-and-data.md)。 + +--- + ## 🗺️ Roadmap ### ✅ 1 · 核心功能 @@ -253,7 +263,7 @@ flutter analyze flutter test ``` -Commit 标题遵循 `PREFIX: 内容` 格式（参考 `git log` 看常用前缀，如 FEAT / FIX / DOCS / MOD / OPT / CHORE / CI / RELEASE 等）。详细贡献流程见 [CONTRIBUTING.md](#)（待补）。本项目遵循 [Contributor Covenant](https://www.contributor-covenant.org/) 行为准则。 +Commit 标题遵循 `PREFIX: 内容` 格式（参考 `git log` 看常用前缀，如 FEAT / FIX / DOCS / MOD / OPT / CHORE / CI / RELEASE 等）。详细贡献流程见 [CONTRIBUTING.md](./CONTRIBUTING.md)。本项目遵循 [Contributor Covenant](https://www.contributor-covenant.org/) 行为准则。 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..98880048 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,32 @@ +# Security Policy + +Echo Loop handles learning materials such as audio files, subtitles, transcripts, speech recordings, and learning progress. Please report security or privacy issues privately before opening a public issue. + +## Reporting a vulnerability + +Email: support@echo-loop.top + +Please include: + +- A short description of the issue. +- Steps to reproduce it. +- Affected platform and app version. +- Whether the issue may expose audio, subtitles, transcripts, recordings, API keys, analytics identifiers, or learning records. +- Any suggested fix, if you have one. + +Please do not include private learning materials unless they are required to reproduce the issue and you have permission to share them. + +## Scope + +Security-sensitive areas include: + +- Local audio, subtitle, transcript, recording, backup, and learning-progress storage. +- AI transcription, translation, sentence analysis, and official collection network requests. +- Analytics, user identifiers, session replay, and consent handling. +- Native iOS, macOS, and Android bridges for speech practice, audio decoding, file access, and permissions. +- Release scripts, signing configuration, and CI workflows. + +## Disclosure + +We will acknowledge valid reports as soon as practical, investigate the issue, and coordinate a fix before public disclosure. Please avoid publishing exploit details until a fixed release or mitigation is available. + diff --git a/docs/growth-playbook.md b/docs/growth-playbook.md new file mode 100644 index 00000000..f14a00eb --- /dev/null +++ b/docs/growth-playbook.md @@ -0,0 +1,168 @@ +# Echo Loop Growth Playbook + +Goal: grow Echo Loop through authentic usage, feedback, and open-source visibility. Do not buy stars, trade stars, automate fake accounts, scrape private contacts, or post the same message repeatedly across communities. + +Current baseline checked on 2026-05-10: 5 GitHub stars. + +## Positioning + +One-line pitch: + +> Echo Loop is an open-source English listening and speaking trainer that guides learners through blind listening, intensive listening, shadowing, retelling, and spaced review. + +Short pitch: + +> Most English apps give you content, but still leave you deciding what to do next. Echo Loop turns one audio clip into a complete practice loop: listen first, understand sentence by sentence, shadow, retell, and review before you forget. It is open source, available on iOS, and supports local audio plus AI subtitles. + +Primary audiences: + +- English learners who already use podcasts, videos, or local audio but lack a repeatable practice method. +- Teachers and self-study groups that need a structured listening and speaking workflow. +- Flutter and open-source developers interested in language-learning apps, audio workflows, ASR, spaced review, and local-first learning tools. + +## Growth targets + +| Stage | Star target | Main proof needed | Primary action | +|---|---:|---|---| +| Baseline | 5 -> 50 | Clear repo page, install path, screenshots | Share with direct learning and Flutter communities | +| Early traction | 50 -> 200 | Real user feedback, bugs fixed quickly | Weekly releases and public changelog posts | +| Community fit | 200 -> 1000 | Repeatable use cases, teachers/groups trying it | Case studies, demo videos, bilingual posts | +| Broad awareness | 1000 -> 5000 | Strong demo, stable Android/iOS path, contributor flow | Launch campaigns, newsletters, curated lists | + +## Repository readiness checklist + +- [x] Clear Chinese README. +- [x] English README. +- [x] Screenshots in README. +- [x] App Store link. +- [x] Android APK link through GitHub Releases. +- [x] Contribution guide. +- [ ] GitHub repository topics set in the repo settings. +- [ ] Pinned release with APK and concise release notes. +- [ ] Short demo video or GIF near the top of README. +- [x] `SECURITY.md` or privacy/security note for audio, subtitles, analytics, and local files. +- [ ] Issue templates for bugs, feature requests, and learning-method feedback. + +Suggested GitHub topics: + +```text +english-learning +language-learning +listening-practice +speaking-practice +shadowing +spaced-repetition +flutter +dart +audio +asr +open-source +education +``` + +## 14-day launch cadence + +Day 1: + +- Confirm latest iOS and Android download links. +- Add GitHub topics. +- Pin the current stable release. +- Create one 60-90 second demo video showing import, intensive listening, shadowing, retelling, and review. + +Day 2: + +- Post to WeChat group and existing personal networks. +- Ask for concrete feedback, not stars. A useful call to action: "Try one 3-minute audio clip and tell us where the loop breaks." + +Day 3: + +- Publish a Chinese long-form post on Zhihu, Juejin, or a personal blog explaining the learning method and why the app is open source. +- Link to the repo and App Store once near the top and once at the end. + +Day 4: + +- Share a Flutter developer post focused on implementation: audio import, subtitle parsing, spaced review, native ASR, Drift, Riverpod. + +Day 5: + +- Open 3-5 beginner-friendly issues with clear scope. +- Label them `good first issue`, `docs`, or `help wanted`. + +Day 6: + +- Post to V2EX or similar developer communities with an honest build log. Ask for product and technical feedback. + +Day 7: + +- Review all comments and issues. +- Ship small fixes quickly and write a concise release note. + +Day 8: + +- Share a before/after clip: "one audio clip, practiced through Echo Loop's full loop." + +Day 9: + +- Reach out manually to 10 English teachers, study-group organizers, or content creators. Personalize every message. + +Day 10: + +- Submit to open-source directories and curated lists related to Flutter, education, language learning, and spaced repetition. + +Day 11: + +- Publish the English post for Reddit, Indie Hackers, Hacker News "Show HN", or Product Hunt. Use community-specific wording and follow each community's rules. + +Day 12: + +- Convert common questions into README FAQ entries. + +Day 13: + +- Share metrics transparently: downloads, stars, issues, fixes, lessons learned. + +Day 14: + +- Decide the next growth bet based on real signals: retention feedback, teacher adoption, Android demand, contributor interest, or content-library demand. + +## Weekly maintenance loop + +- Monday: check star/download issue metrics and update `docs/star-growth-log.md`. +- Tuesday: ship one user-visible improvement or documentation fix. +- Wednesday: publish one learning-method or build-log post. +- Thursday: reply to issues, discussions, and community comments. +- Friday: package a release note with screenshots or short clips. + +## Channel guidance + +GitHub: + +- Keep releases frequent and clear. +- Use labels so new contributors can find work. +- Avoid asking only for stars. Ask users to try the app, report friction, and star only if they want to follow the project. + +Zhihu / Juejin / WeChat: + +- Lead with the learning pain: learners do not know what to do next after opening audio. +- Explain the loop and show screenshots. +- Include concrete usage steps. + +V2EX / developer communities: + +- Lead with the build story and technical tradeoffs. +- Be explicit that feedback is welcome. +- Do not cross-post identical text. + +Reddit / HN / Product Hunt: + +- Use English copy. +- Make the demo link obvious. +- Be ready to answer privacy, offline, Android, and roadmap questions. + +## Guardrails + +- Do not automate starring, comments, votes, follows, or fake accounts. +- Do not mass-DM strangers. +- Do not hide that the maintainer is affiliated with the project. +- Do not promise learning outcomes the app cannot prove. +- Do not reuse competitor trademarks in ads beyond fair comparison in documentation. diff --git a/docs/launch-copy.md b/docs/launch-copy.md new file mode 100644 index 00000000..e13830d9 --- /dev/null +++ b/docs/launch-copy.md @@ -0,0 +1,150 @@ +# Launch Copy + +Use these as starting points. Adapt each post to the community instead of copying the same text everywhere. + +## Chinese short post + +标题： + +```text +我做了一个开源英语听说训练 App：把盲听、精听、跟读、复述和复习串成一个闭环 +``` + +正文： + +```text +Echo Loop 是一个开源英语听说训练 App。 + +它不是再给你一堆材料，而是把一段音频练透：先盲听，再逐句精听，接着跟读、复述，最后按间隔复习把难句拉回来。 + +我做它的原因很简单：很多人不是不愿意练英语，而是每次打开材料都要重新判断下一步该做什么。Echo Loop 会直接告诉你当前步骤，把练习节奏自动推下去。 + +目前支持： +- 导入本地音频和字幕，也可以用 AI 生成字幕 +- 逐句精听、长难句意群划分 +- 跟读评测、段落复述 +- 难句收藏、语境化闪卡和间隔复习 +- iOS 已上架，Android APK 可在 GitHub Releases 下载 + +GitHub: https://github.com/echo-loop/Echo-Loop +App Store: https://apps.apple.com/cn/app/echo-loop-%E9%AB%98%E6%95%88%E8%8B%B1%E8%AF%AD%E5%90%AC%E8%AF%B4%E8%AE%AD%E7%BB%83/id6760324074 + +如果你正在练英语，欢迎拿一段 3 分钟音频试一次完整流程。更希望收到具体反馈：哪一步卡住了、哪里不够顺、哪些功能会让你继续用。 +``` + +## English short post + +Title: + +```text +Echo Loop: an open-source English listening and speaking trainer +``` + +Body: + +```text +I built Echo Loop, an open-source app for English listening and speaking practice. + +Instead of giving learners more content and leaving them to figure out what to do next, Echo Loop turns one audio clip into a complete practice loop: blind listening, intensive listening, shadowing, retelling, and spaced review. + +It supports local audio import, subtitles, AI-generated transcripts, sentence-by-sentence listening, hard-sentence review, contextual flashcards, and shadowing evaluation. + +Repo: https://github.com/echo-loop/Echo-Loop +App Store: https://apps.apple.com/cn/app/echo-loop-%E9%AB%98%E6%95%88%E8%8B%B1%E8%AF%AD%E5%90%AC%E8%AF%B4%E8%AE%AD%E7%BB%83/id6760324074 + +I would appreciate concrete feedback from English learners, teachers, and Flutter developers. Try one short audio clip and tell me where the learning loop breaks or feels awkward. +``` + +## Show HN draft + +```text +Show HN: Echo Loop, an open-source app for English listening and speaking practice + +Hi HN, I built Echo Loop, an open-source Flutter app for structured English listening and speaking practice. + +The idea is to make the practice method explicit. A learner imports an audio clip, then Echo Loop guides them through blind listening, sentence-by-sentence intensive listening, shadowing, retelling, and spaced review. + +Why I built it: many learners already have enough content, but still have to decide what to do next, how many times to repeat, what to review, and when to come back. Echo Loop tries to automate that practice rhythm. + +It currently supports local audio import, subtitles or AI-generated transcripts, sense-group splitting for long sentences, hard-sentence review, contextual flashcards, and ASR-based shadowing evaluation. + +GitHub: https://github.com/echo-loop/Echo-Loop +App Store: https://apps.apple.com/cn/app/echo-loop-%E9%AB%98%E6%95%88%E8%8B%B1%E8%AF%AD%E5%90%AC%E8%AF%B4%E8%AE%AD%E7%BB%83/id6760324074 + +I would love feedback on the learning flow, the product shape, and the Flutter/audio implementation. +``` + +## Reddit draft + +```text +I built an open-source app that guides English learners through a full listening/speaking loop + +I have been working on Echo Loop, an open-source app for English listening and speaking practice. + +The core workflow is: +1. Blind listen to a short audio clip. +2. Go sentence by sentence until the content is clear. +3. Shadow the speaker. +4. Retell the paragraph in your own words. +5. Review hard sentences later with spaced repetition. + +It supports local audio, subtitles, AI transcripts, saved hard sentences, contextual flashcards, and shadowing evaluation. + +GitHub: https://github.com/echo-loop/Echo-Loop + +I am looking for practical feedback from learners and teachers: would this workflow fit your study routine, and where would it feel too heavy? +``` + +## Flutter developer post + +```text +Echo Loop is an open-source Flutter app for English listening and speaking practice. + +Technical areas that may be useful to other Flutter developers: +- local audio import and playback +- subtitle parsing and sentence tracking +- Drift persistence for learning state +- Riverpod-based learning flow +- native iOS/macOS/Android bridges for speech and audio processing +- spaced review scheduling and local notifications + +Repo: https://github.com/echo-loop/Echo-Loop + +Feedback on architecture, platform support, and test coverage is welcome. +``` + +## Direct outreach template + +```text +Hi {name}, I am building Echo Loop, an open-source app for English listening and speaking practice. + +It guides learners through one complete loop: blind listening, intensive listening, shadowing, retelling, and spaced review. + +I noticed your work around {specific class/community/content}. If you have 10 minutes, could you try one short audio clip and tell me where the workflow feels useful or awkward? + +GitHub: https://github.com/echo-loop/Echo-Loop +App Store: https://apps.apple.com/cn/app/echo-loop-%E9%AB%98%E6%95%88%E8%8B%B1%E8%AF%AD%E5%90%AC%E8%AF%B4%E8%AE%AD%E7%BB%83/id6760324074 + +No pressure to promote it. I am mainly looking for concrete product feedback. +``` + +## Release note template + +```text +Echo Loop {version} + +Highlights: +- {user-visible change} +- {bug fix} +- {learning-flow improvement} + +Try it: +- iOS: {app_store_link} +- Android APK: {release_link} + +Feedback wanted: +- Does the practice loop feel clear? +- Which step has the most friction? +- What would make you use it again tomorrow? +``` + diff --git a/docs/privacy-and-data.md b/docs/privacy-and-data.md new file mode 100644 index 00000000..ca027811 --- /dev/null +++ b/docs/privacy-and-data.md @@ -0,0 +1,62 @@ +# Privacy and Data Notes + +This document summarizes data-sensitive behavior visible from the open-source codebase. The in-app privacy policy remains the user-facing legal policy: + +- Terms: https://www.echo-loop.top/terms +- Privacy policy: https://www.echo-loop.top/privacy + +## Local learning materials + +Echo Loop is designed around user-selected learning materials: + +- Local audio files. +- Local subtitle files. +- Generated transcripts. +- Saved hard sentences, saved words, flashcards, review state, and learning progress. +- Speech-practice recordings or temporary audio files created during practice. + +These files and records should be treated as private user data. Do not ask users to upload private materials in public GitHub issues. If a sample is needed for debugging, ask for a minimal non-private reproduction file. + +## Networked features + +Some features may contact Echo Loop services or third-party services depending on build configuration and user action: + +- AI transcription, translation, sentence analysis, and vocabulary explanation. +- Official curated collections and remote collection metadata/content downloads. +- Update checks and release download links. +- Region lookup used by analytics/network configuration. + +When documenting or changing these features, be explicit about whether user-provided audio, subtitles, transcripts, recordings, or derived text leave the device. + +## Analytics + +The current release-mode analytics path uses PostHog when configured in code. Firebase and Umeng channels exist in the codebase as fallback or legacy options, but the current provider comments indicate PostHog is the active release channel. + +Analytics-related changes should be reviewed carefully because they may involve: + +- A generated app user identifier. +- Screen and feature usage events. +- Super properties or user properties. +- Session replay configuration on supported platforms. +- Region or platform metadata. + +Do not add analytics events containing raw audio text, full transcripts, speech recordings, imported file names, private collection names, or user-entered learning content unless there is an explicit privacy review and user-facing disclosure. + +## Contributor checklist for data-sensitive changes + +- Avoid logging private learning content. +- Avoid including private file paths in analytics or crash reports. +- Keep debug logs out of release behavior when they may contain private content. +- Prefer aggregate counts and state transitions over raw content. +- Update this document and the user-facing privacy policy when behavior changes. +- Add tests around deletion, export, backup, permission, or consent behavior when applicable. + +## Public issue guidance + +For bugs involving private content: + +- Describe the symptom and platform. +- Share a synthetic sample when possible. +- Redact filenames, transcripts, personal notes, and recordings. +- Use the private security contact for suspected leaks or exposure. + diff --git a/docs/star-growth-log.md b/docs/star-growth-log.md new file mode 100644 index 00000000..db3c64d2 --- /dev/null +++ b/docs/star-growth-log.md @@ -0,0 +1,47 @@ +# Star Growth Log + +Use this file to track real growth work and avoid relying on vague impressions. + +Baseline checked on 2026-05-10: 5 stars. + +## Weekly metrics + +| Week | Stars | Delta | Downloads | Issues opened | Issues closed | Posts shipped | Notes | +|---|---:|---:|---:|---:|---:|---:|---| +| 2026-05-10 | 5 | - | - | - | - | - | Baseline | + +## Campaign log + +| Date | Channel | Link | Audience | CTA | Result | Follow-up | +|---|---|---|---|---|---|---| +| 2026-05-10 | GitHub | https://github.com/echo-loop/Echo-Loop | Open-source users | Try the app and give feedback | Baseline 5 stars | Add topics, release notes, demo video | + +## Experiment template + +```text +Date: +Hypothesis: +Audience: +Asset: +Channel: +Call to action: +Result after 24h: +Result after 7d: +What to change next: +``` + +## Quality signals to track + +- Stars from people who also open issues, discussions, or PRs. +- Downloads after each release post. +- Users who complete one full audio practice loop. +- Teachers or groups willing to test with multiple learners. +- Repeat visitors in community discussions. + +## Anti-signals + +- Stars without any downloads, feedback, or retention. +- Repeated copy-paste posts removed by communities. +- Low-quality comments caused by vague calls to action. +- Users confused about platform availability or privacy. +