diff --git a/QUICK_START_GUIDE.txt b/QUICK_START_GUIDE.txt index 8f720c8..7133b9c 100644 --- a/QUICK_START_GUIDE.txt +++ b/QUICK_START_GUIDE.txt @@ -1,52 +1,65 @@ -GITCORD BOT - QUICK START GUIDE -================================ - -1. LINK YOUR GITHUB ACCOUNT (Required First Step) ---------------------------------------------------- -Type in Discord: /link -• Bot will DM you a verification code -• Comment that code on any GitHub issue/PR -• Return to Discord and type: /verify-link - -2. AVAILABLE COMMANDS -------------------- -/link - Start GitHub identity linking -/verify-link - Complete identity verification -/unlink - Remove your GitHub link -/status - Check your linked GitHub account -/metrics - View your contribution stats -/request-issue - Request an issue assignment (needs mentor approval) -/assign-issue - Directly assign yourself to an issue (mentors only) -/sync - Manually sync data (mentors only) -/issue-requests - View pending issue requests (mentors only) - -3. HOW TO REQUEST AN ISSUE --------------------------- -1. Find an issue on GitHub you want to work on -2. Copy the issue URL -3. In Discord type: /request-issue -4. A mentor will review and approve your request -5. Once approved, the issue is assigned to you on GitHub - -4. FOR MENTORS --------------- -• /assign-issue - Instantly assign issue to yourself or others -• /sync - Refresh all data and apply pending changes -• /issue-requests - View all pending requests from contributors - -5. HOW SCORING WORKS --------------------- -• PR merged = +10 points (base) -• Difficulty labels adjust score (easy/medium/hard) -• Quality bonuses: PR review (+2), helpful comment (+1) -• Quality penalties: Reverted PR (-5), failed CI merge (-3) -• Top contributors get Discord roles automatically - -6. TIPS +GITCORD — QUICK START GUIDE +=========================== + +Gitcord links Discord and GitHub for verified contributors, then helps with +profiles, contribution summaries, PR lookups, and scheduler notifications. + +Works in the AOSSIE and Stability Nexus Discord servers (separate bot stacks). + + +1. LINK YOUR GITHUB ACCOUNT (required first) +-------------------------------------------- +In Discord: + + /link github_username: + +• Bot replies (ephemeral) with a short verification code and a Verify button +• Paste that code into your GitHub profile bio OR a public gist +• Click Verify in Discord, or run: /verify-link github_username: + +Tips: +• Code is short-lived — if it expires, run /link again +• You can remove the code from your bio/gist after you are verified +• Need to switch accounts? /unlink, then /link again + + +2. CONTRIBUTOR COMMANDS +----------------------- +/link Link Discord → GitHub (get verification code) +/verify-link Complete verification after placing the code +/profile Your (or another member’s) Gitcord profile +/who-is Look up a GitHub username → Discord + link freshness +/summary Contribution metrics (7d / 30d); optional member +/open-prs List currently open PRs for a contributor +/pr Recent PRs by closed / merged / open (count, skip) +/connect-social Attach X or LinkedIn username/URL to your profile +/disconnect-social Remove X or LinkedIn from your profile +/unlink Remove your GitHub link + + +3. MENTOR COMMAND +----------------- +/sync Manually sync GitHub events and send notifications + (requires a mentor role from discord.command_permissions) + + +4. WHAT HAPPENS AFTER YOU VERIFY +-------------------------------- +• Scheduler cycles ingest GitHub activity for configured repos +• Notifications go to verified Discord users only (DMs / mapped channels) +• /profile and /summary use your verified GitHub identity +• Org settings may live in the org’s .github/gitcord.yaml (remote config) + + +5. TIPS ------- -• Must be verified (/link + /verify-link) to use most commands -• Use /metrics to track your progress -• Request issues early - they're assigned on first-come basis -• Stay active to maintain contributor roles +• Most commands need a verified link — start with /link +• Use /profile to confirm you are verified and see socials/roles +• Use /who-is when you know a GitHub login but not the Discord account +• Use /pr or /open-prs for PR status without leaving Discord +• Mentors: prefer dry-run / observer modes for bulk GitHub writes + -Need help? Type /status to check your verification status. +Need help? +• Docs: README.md, docs/IDENTITY_VERIFICATION.md, INSTALLATION.md +• Discord: #gitcord (AOSSIE) — ask maintainers or open a GitHub issue diff --git a/README.md b/README.md index a43726f..4602c25 100644 --- a/README.md +++ b/README.md @@ -84,8 +84,8 @@ Gitcord is a local, offline‑first automation engine that reads GitHub activity 4. [Brand kit](brand/Brand.md) - Logo, colors, typography, icons 5. [Maintainers](MAINTAINERS.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Best Practices](BestPracticesChecklist.md) 6. [AOSSIE Discord — Gitcord thread](https://discord.com/channels/1022871757289422898/1465995983791063140) -4. [Technical Documentation](TECHNICAL_DOCUMENTATION.md) - Architecture and design -5. [Docker Guide](docs/DOCKER.md) - Docker setup and mentor-friendly deployment +7. [Technical Documentation](TECHNICAL_DOCUMENTATION.md) - Architecture and design +8. [Docker Guide](docs/DOCKER.md) - Docker setup and mentor-friendly deployment --- @@ -277,6 +277,8 @@ Wait 30 seconds for commands to sync. ## 🤖 Discord Bot Commands +Contributor-facing cheat sheet: [`QUICK_START_GUIDE.txt`](QUICK_START_GUIDE.txt). + ### Identity Linking - `/link` - Link your Discord account to GitHub (creates verification code)