From f6238232bef7fa8ad1ae815c50a19cc7c422735f Mon Sep 17 00:00:00 2001 From: adgk2349 Date: Sat, 7 Mar 2026 22:56:19 +0900 Subject: [PATCH] docs: add contributor onboarding templates and guides --- .github/ISSUE_TEMPLATE/bug_report.yml | 65 ++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 48 ++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 28 +++++++ CONTRIBUTING.md | 90 +++++++++++++++++++++ README.ja.md | 14 ++++ README.ko.md | 14 ++++ README.md | 14 ++++ docs/good-first-issues.md | 91 ++++++++++++++++++++++ 9 files changed, 369 insertions(+) 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/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/good-first-issues.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..34b8c9a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,65 @@ +name: Bug report +description: Report a reproducible defect in FlowMap. +title: "[Bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug. Please provide a minimal reproduction so we can fix it quickly. + + - type: textarea + id: summary + attributes: + label: Summary + description: What is broken? + placeholder: FlowMap does not show changed nodes when saving Swift files. + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Provide exact steps from a clean workspace. + placeholder: | + 1. Open workspace ... + 2. Save file ... + 3. Run FlowMap: Analyze Workspace ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + placeholder: Changed node should be highlighted as yellow. + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + placeholder: No diff highlight appears. + validations: + required: true + + - type: textarea + id: env + attributes: + label: Environment + description: OS, Xcode/Swift version, VS Code version, extension version. + placeholder: macOS 14.7, Swift 6.0, VS Code 1.98, FlowMap commit abc123 + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs / screenshots + description: Include console logs, screenshots, or replay output if relevant. + placeholder: Paste logs here. + validations: + required: false + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..65d59e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Usage question + url: mailto:adgk2349b@gmail.com + about: Ask usage or setup questions by email. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..b4093fa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,48 @@ +name: Feature request +description: Suggest an improvement for FlowMap. +title: "[Feature] " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Please describe the user problem first, then propose a solution. + + - type: textarea + id: problem + attributes: + label: Problem statement + description: What pain point are you trying to solve? + placeholder: It is hard to detect risky graph diffs at a glance. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: What should change? + placeholder: Add risk score badge for diff mode. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + placeholder: Keep current legend only, add external script, etc. + validations: + required: false + + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: Define testable outcomes. + placeholder: | + - [ ] Badge appears in diff mode + - [ ] Risk score updates on save + - [ ] Unit tests added + validations: + required: true + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..198e759 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,28 @@ +## Summary + + + +## What Changed + + + +## Validation + + + +```bash +cargo test +``` + +## Screenshots / Demo (if UI changed) + + + +## Checklist + +- [ ] Linked related issue (if available) +- [ ] Added/updated tests for behavior changes +- [ ] Ran required local checks (`fmt`, `clippy`, `test`, extension compile/lint) +- [ ] Updated docs/README if user-visible behavior changed +- [ ] Included replay/scenario report when diff detection behavior changed + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c4f8c64 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,90 @@ +# Contributing to FlowMap + +Thanks for contributing to FlowMap. + +This document is optimized for first-time contributors. If you are looking for a starting point, check [docs/good-first-issues.md](docs/good-first-issues.md). + +## Quick Start (5-10 minutes) + +1. Fork and clone this repository. +2. Create a branch: + - `feat/` for features + - `fix/` for fixes + - `docs/` for documentation +3. Run local checks before opening a PR. + +## Local Setup + +Prerequisites: + +- macOS +- Rust toolchain +- Swift toolchain / Xcode command line tools +- Node.js 20+ + +Build commands: + +```bash +cargo build +cd parsers/swift-ast && swift build -c release && cd ../.. +cd editor/vscode && npm ci && npm run compile && cd ../.. +``` + +## Required Checks Before PR + +Run these in repo root: + +```bash +cargo fmt --check +cargo clippy -- -D warnings +cargo test +cd editor/vscode && npm run lint && npm run compile && cd ../.. +``` + +If your change affects analysis/diff behavior, also attach validation output: + +```bash +node scripts/run_sample_scenarios.mjs --report reports/sample-scenarios-report.json +node scripts/run_commit_replay.mjs --repo /path/to/swift-repo --count 20 --report reports/replay-local.json +``` + +## Pull Request Guidelines + +- Keep PR scope small and reviewable. +- Include a short problem statement and what changed. +- Include before/after behavior. +- For graph UI changes, include screenshots or GIF. +- For parser/engine logic changes, include at least one regression test. + +Maintainer target: first review response within 48 hours for new contributors. + +## First Contribution Checklist + +- Pick one item from [docs/good-first-issues.md](docs/good-first-issues.md) +- Reproduce and confirm current behavior +- Add or update tests +- Run required checks +- Open PR using the provided PR template +- Request review + +## Reporting Issues + +Use GitHub Issue templates: + +- Bug report: reproducible defect +- Feature request: problem + proposal + acceptance criteria + +## Code Style Notes + +- Rust: keep clippy clean; avoid panic-prone changes in engine paths. +- TypeScript/JS: keep webview code modular (`graph.*.js` split). +- Swift parser: prioritize stable JSON schema output for engine compatibility. + +## Validation Evidence in README + +Bundled validation reports live under `reports/`. If you update benchmark/replay reports, include: + +- what dataset/repo was used +- command used +- summary metrics (TP/TN/FP/FN, detection rate) + diff --git a/README.ja.md b/README.ja.md index a87cfaa..d0425bd 100644 --- a/README.ja.md +++ b/README.ja.md @@ -2,6 +2,8 @@ > Swift コードの構造と呼び出し関係をグラフ分析するツールです。AI が生成したコード変更の検証に特に役立ちます。 +[![CI](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml/badge.svg)](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml) + [English](README.md) · [한국어](README.ko.md) ## FlowMap とは @@ -136,6 +138,14 @@ node scripts/run_commit_replay.mjs \ - `reports/replay-validation-bundle.md` - `reports/replay-validation-bundle.json` +最新の統合メトリクス（`reports/replay-validation-bundle.md`）: + +- コミットペア総数: 209 +- TP / TN / FP / FN: 106 / 97 / 0 / 6 +- Non-Swift FP Rate: 0% +- Swift Detection Rate: 94.64% +- Overall Match Rate: 97.13% + ## ライセンス FlowMap は source-available モデルで提供されています。 @@ -161,6 +171,10 @@ FlowMap は source-available モデルで提供されています。 Issue と Pull Request を歓迎します。 +- コントリビューションガイド: [CONTRIBUTING.md](CONTRIBUTING.md) +- 初回向けタスク一覧: [docs/good-first-issues.md](docs/good-first-issues.md) +- Issue / PR は `.github` のテンプレートを利用してください + 貢献しやすい領域: - Swift 解析の edge case diff --git a/README.ko.md b/README.ko.md index a9aa5c9..e954f83 100644 --- a/README.ko.md +++ b/README.ko.md @@ -2,6 +2,8 @@ > Swift 코드의 구조와 호출 관계를 그래프로 분석하는 도구입니다. AI가 생성한 코드 변경을 검증할 때 특히 유용합니다. +[![CI](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml/badge.svg)](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml) + [English](README.md) · [日本語](README.ja.md) ## FlowMap이란? @@ -136,6 +138,14 @@ node scripts/run_commit_replay.mjs \ - `reports/replay-validation-bundle.md` - `reports/replay-validation-bundle.json` +최신 통합 지표(`reports/replay-validation-bundle.md`): + +- 전체 커밋 페어: 209 +- TP / TN / FP / FN: 106 / 97 / 0 / 6 +- Non-Swift FP Rate: 0% +- Swift Detection Rate: 94.64% +- Overall Match Rate: 97.13% + ## 라이선스 FlowMap은 source-available 방식으로 제공됩니다. @@ -161,6 +171,10 @@ FlowMap은 source-available 방식으로 제공됩니다. 이슈와 PR은 환영합니다. +- 기여 가이드: [CONTRIBUTING.md](CONTRIBUTING.md) +- 시작용 작업 목록: [docs/good-first-issues.md](docs/good-first-issues.md) +- 이슈/PR 작성 시 `.github` 템플릿을 사용해주세요 + 기여하기 좋은 영역: - Swift 파싱 edge case diff --git a/README.md b/README.md index 34785ad..01fa811 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ > Swift code graph and impact analysis tool — understand and verify code structure, especially when reviewing AI-generated changes. +[![CI](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml/badge.svg)](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml) + [한국어](README.ko.md) · [日本語](README.ja.md) ## What is FlowMap? @@ -136,6 +138,14 @@ Current bundled validation output: - `reports/replay-validation-bundle.md` - `reports/replay-validation-bundle.json` +Latest bundled metrics (`reports/replay-validation-bundle.md`): + +- Total commit pairs: 209 +- TP / TN / FP / FN: 106 / 97 / 0 / 6 +- Non-Swift FP Rate: 0% +- Swift Detection Rate: 94.64% +- Overall Match Rate: 97.13% + ## License FlowMap is source-available. @@ -161,6 +171,10 @@ For commercial licensing inquiries, contact: adgk2349b@gmail.com Issues and pull requests are welcome. +- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md) +- Starter tasks: [docs/good-first-issues.md](docs/good-first-issues.md) +- Use the Issue/PR templates in `.github/` + Good areas to contribute: - Swift parsing edge cases diff --git a/docs/good-first-issues.md b/docs/good-first-issues.md new file mode 100644 index 0000000..0ba4192 --- /dev/null +++ b/docs/good-first-issues.md @@ -0,0 +1,91 @@ +# Good First Issues + +This list is designed for first-time contributors. Each item is intentionally small, testable, and reviewable. + +## 1) Diff Legend Tooltip Clarification + +- Area: `editor/vscode/webview/graph.html` +- Goal: Improve wording for Added/Removed/Changed/Impacted legend items. +- Acceptance: + - Updated tooltip copy is concise and consistent. + - No layout break on desktop/mobile webview. + +## 2) Auto-Analyze Status Message Refinement + +- Area: `editor/vscode/src/extension.ts` +- Goal: Improve toggle message clarity for `flowmap.toggleAutoAnalyzeOnSave`. +- Acceptance: + - Message clearly states enabled/disabled state. + - Unit or integration behavior unchanged. + +## 3) Add Test for Non-Git Workspace Diff Fallback + +- Area: `crates/engine/src/git_diff.rs` +- Goal: Extend tests for non-git directory behavior. +- Acceptance: + - New test added and passing under `cargo test`. + - No regression in existing tests. + +## 4) README: Add Quick Troubleshooting Section + +- Area: `README.md`, `README.ko.md`, `README.ja.md` +- Goal: Add a short troubleshooting block for parser path/build issues. +- Acceptance: + - Includes at least 3 common problems with fixes. + - Language consistency maintained in each README. + +## 5) Webview Empty-State Copy Improvement + +- Area: `editor/vscode/webview/graph.js` +- Goal: Improve no-analysis prompt wording. +- Acceptance: + - Message is action-oriented. + - Existing analyze button flow still works. + +## 6) Add Small Unit Test for GraphDiff Metadata Change + +- Area: `crates/engine/src/graph_diff.rs` tests +- Goal: Ensure `changed_nodes` catches node metadata updates. +- Acceptance: + - New unit test fails before fix and passes after. + +## 7) Add `npm run typecheck` Script in Extension + +- Area: `editor/vscode/package.json` +- Goal: Add a script alias for TS compile checks. +- Acceptance: + - Script runs successfully in CI/local. + - README/CONTRIBUTING updated with command. + +## 8) Improve File Detail Mode Node Spacing + +- Area: `editor/vscode/webview/graph.layouts.js` +- Goal: Slightly improve readability of dense function lists. +- Acceptance: + - Layout overlap reduced on sample screenshot. + - No severe regression in Calls/Overview modes. + +## 9) Add Replay Command Example for Small Repos + +- Area: `README*.md` +- Goal: Add a short replay command with `--count 20`. +- Acceptance: + - Command copy-pastable. + - Mentions expected output file path. + +## 10) Add "Needs Repro" Label Guide + +- Area: `CONTRIBUTING.md` +- Goal: Add rule for triaging incomplete bug reports. +- Acceptance: + - Label usage policy documented in 3-5 lines. + - Keeps issue response process clear. + +--- + +If you are taking one issue, comment with: + +`I can take this issue.` + +Maintainer target is first response within 48 hours. +