Merge pull request #8 from AOSSIE-Org/chore/project-consistency-docs-ci

Align scoring configs, add docs, CI workflow, and related fixes

Author: shubham5080

.github/workflows/sync-pr-labels.yml

@@ -199,46 +199,61 @@ jobs:
               pull_number: prNumber
             });
             
-            const additions = pr.data.additions;
-            const deletions = pr.data.deletions;
+            const additions = pr.data.additions ?? 0;
+            const deletions = pr.data.deletions ?? 0;
             const totalChanges = additions + deletions;
             
             console.log(`PR has ${additions} additions and ${deletions} deletions (${totalChanges} total changes)`);
             
             // Determine size label based on total changes
             let sizeLabel = '';
-            if (totalChanges <= 10) {
+            if (Number.isFinite(totalChanges) && totalChanges <= 10) {
               sizeLabel = 'size/XS';
-            } else if (totalChanges <= 50) {
+            } else if (Number.isFinite(totalChanges) && totalChanges <= 50) {
               sizeLabel = 'size/S';
-            } else if (totalChanges <= 200) {
+            } else if (Number.isFinite(totalChanges) && totalChanges <= 200) {
               sizeLabel = 'size/M';
-            } else if (totalChanges <= 500) {
+            } else if (Number.isFinite(totalChanges) && totalChanges <= 500) {
               sizeLabel = 'size/L';
-            } else {
+            } else if (Number.isFinite(totalChanges)) {
               sizeLabel = 'size/XL';
             }
             
+            if (!sizeLabel) {
+              console.log('Skipping size label: could not compute change stats');
+              return;
+            }
+            
             console.log(`Applying size label: ${sizeLabel}`);
             
             // Remove any existing size labels first
             const currentLabels = await github.rest.issues.listLabelsOnIssue({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              issue_number: prNumber
+              issue_number: prNumber,
+              per_page: 100
             });
             
             const sizeLabelsToRemove = currentLabels.data
               .map(label => label.name)
               .filter(name => name.startsWith('size/'));
             
             for (const label of sizeLabelsToRemove) {
-              await github.rest.issues.removeLabel({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: prNumber,
-                name: label
-              });
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: prNumber,
+                  name: label
+                });
+              } catch (e) {
+                const status = e.status ?? e.response?.status;
+                if (status === 404) {
+                  console.log(`Label already absent, skipping remove: ${label}`);
+                } else {
+                  throw e;
+                }
+              }
             }
             
             // Apply the new size label

.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Python Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[dev]
+
+      - name: Run tests
+        run: pytest

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to Gitcord
+
+Thanks for your interest in improving Gitcord.
+
+## Setup
+
+1. Fork and clone the repository.
+2. Create and activate a virtual environment.
+3. Install project dependencies (runtime + dev extras: `pytest`, `ruff`):
+   - `./.venv/bin/python -m pip install -e ".[dev]"`
+
+## Development Workflow
+
+1. Create a feature branch from `main`.
+2. Make focused changes with clear commit messages.
+3. Run tests locally:
+   - `pytest`
+4. Open a pull request with:
+   - What changed
+   - Why it changed
+   - How it was tested
+
+## Coding Guidelines
+
+- Keep changes small and scoped.
+- Preserve offline-first and audit-first behavior.
+- Prefer deterministic logic in planning/scoring paths.
+- Update docs/config examples when behavior changes.
+
+## Pull Request Checklist
+
+- [ ] Tests pass locally
+- [ ] Docs updated when needed
+- [ ] Config examples still match runtime behavior
+- [ ] No secrets committed

README.md

@@ -219,7 +219,7 @@ Wait 30 seconds for commands to sync.
 2. **Live role updates:** To have the bot actually add/remove roles in Discord, set in your config:
    - `runtime.mode: "active"`
    - `discord.permissions.write: true`
-     Then run `run-once` again. Ensure the bot’s role in the server is **above** any roles it should assign (Server Settings → Roles). See [Testing in Discord](docs/TESTING_DISCORD.md) for details.
+    Then run `run-once` again. Ensure the bot’s role in the server is **above** any roles it should assign (Server Settings → Roles). See [Testing in Discord](docs/TESTING_DISCORD.md) for details.
 
 ---
 
@@ -257,7 +257,7 @@ Not applicable (CLI automation engine).
 
 ## 🙌 Contributing
 
-Thank you for considering contributing to this project! Contributions are highly appreciated and welcomed. To ensure smooth collaboration, please refer to our [Contribution Guidelines](./CONTRIBUTING.md).
+Thank you for considering contributing to this project! Contributions are highly appreciated and welcomed. To ensure smooth collaboration, please refer to our [Contribution Guidelines](CONTRIBUTING.md).
 
 ---
 

config/aussie.yaml

@@ -3,30 +3,43 @@
 # For Docker: set data_dir to "/data" and use: docker compose run --rm bot --config /app/config/aussie.yaml bot
 
 runtime:
-  mode: "dry-run"
+  mode: "active"
   log_level: "INFO"
   data_dir: "./data/aussie"
   github_adapter: "ghdcbot.adapters.github.rest:GitHubRestAdapter"
   discord_adapter: "ghdcbot.adapters.discord.api:DiscordApiAdapter"
   storage_adapter: "ghdcbot.adapters.storage.sqlite:SqliteStorage"
+  # Notifications still run; these only skip score computation and Discord role add/remove.
+  enable_scoring: false
+  enable_discord_role_updates: false
 
 github:
   org: "AOSSIE-Org"
   token: "${GITHUB_TOKEN}"
   api_base: "https://api.github.com"
   permissions:
     read: true
-    write: false
+    write: true
   user_fallback: false
 
 discord:
   guild_id: "1022871757289422898"
   token: "${DISCORD_TOKEN}"
   permissions:
     read: true
-    write: false
+    write: true
   activity_channel_id: null
   pr_preview_channels: []
+  # Verified GitHub → Discord DMs (or channel if channel_id is set). Requires linked users (/link + /verify-link).
+  notifications:
+    enabled: true
+    issue_assignment: true
+    pr_review_requested: true
+    pr_review_result: true
+    pr_merged: true
+    coderabbit_reminders: false
+    coderabbit_reminder_after_hours: 48
+    channel_id: null  # null = DM; set to a channel ID to post there instead
 
 scoring:
   period_days: 30
@@ -51,4 +64,3 @@ assignments:
 
 repo_contributor_roles: {}
 
-identity_mappings: []

config/docker-example.yaml

@@ -30,10 +30,8 @@ discord:
 scoring:
   period_days: 30
   weights:
-    issue_opened: 3
-    pr_opened: 5
-    pr_reviewed: 2
-    comment: 1
+    # Base scoring currently uses merged PR events.
+    pr_merged: 5
 
 role_mappings:
   - discord_role: "Contributor"

config/example.yaml

@@ -48,10 +48,8 @@ discord:
 scoring:
   period_days: 30
   weights:
-    issue_opened: 3
-    pr_opened: 5
-    pr_reviewed: 2
-    comment: 1
+    # Base scoring currently uses merged PR events.
+    pr_merged: 5
 
 role_mappings:
   - discord_role: "Contributor"

docs/TESTING_DISCORD.md

@@ -0,0 +1,34 @@
+# Testing in Discord
+
+This guide explains how to safely validate Gitcord role automation in a Discord server.
+
+## Recommended Test Sequence
+
+1. **Dry-run phase (no Discord role mutations):** In your config, set:
+   - `runtime.mode: "dry-run"`
+   - `runtime.enable_discord_role_updates: false`
+   - `discord.permissions.write: false`  
+   With `enable_discord_role_updates: false`, `run-once` will not apply Discord role add/remove even if mode or permissions were mis-set.
+2. Run a sync:
+   - `python -m ghdcbot.cli --config config/my-org-config.yaml run-once`
+3. Review the generated report at `<data_dir>/reports/audit.md`.
+4. Verify planned role changes and identity mappings are correct.
+5. **Live phase (apply role updates):** Only after review, set:
+   - `runtime.mode: "active"`
+   - `runtime.enable_discord_role_updates: true`
+   - `discord.permissions.write: true`
+6. Run `run-once` again and confirm expected role changes in Discord.
+
+## Discord Permission Checklist
+
+- Bot has `Manage Roles`, `View Channels`, `Send Messages`, `Embed Links`, and `Read Message History`.
+- Bot role is above any role it should assign/remove.
+- Application has `Server Members Intent` enabled in Discord Developer Portal.
+
+## Bot Command Smoke Tests
+
+- Identity: `/link`, `/verify-link`, `/verify`, `/status`, `/unlink`
+- Metrics: `/summary`, `/pr-info`
+- Mentor actions (with configured role): `/request-issue`, `/assign-issue`, `/issue-requests`, `/sync`
+
+If slash commands do not appear immediately, wait for command sync and ensure the configured `discord.guild_id` is correct.

src/ghdcbot/bot.py

@@ -1726,14 +1726,19 @@ async def sync_cmd(interaction: discord.Interaction) -> None:
             )
 
             await interaction.followup.send("🔄 Syncing GitHub events and sending notifications...", ephemeral=True)
-            
-            # Run orchestrator (this will ingest and send notifications)
-            orchestrator.run_once()
-            
+
+            # run_once() is synchronous and can take many minutes for large orgs; running it on the
+            # event loop blocks Discord heartbeats and delays other slash commands (they then hit
+            # "application did not respond"). Run it in a worker thread instead.
+            def _run_sync_and_close() -> None:
+                try:
+                    orchestrator.run_once()
+                finally:
+                    orchestrator.close()
+
+            await asyncio.to_thread(_run_sync_and_close)
+
             await interaction.followup.send("✅ Sync complete! Notifications sent for new GitHub events.", ephemeral=True)
-            
-            # Cleanup
-            orchestrator.close()
         except Exception as exc:
             logger.exception("Sync failed", exc_info=True)
             await interaction.followup.send(

src/ghdcbot/config/models.py

@@ -36,6 +36,10 @@ class RuntimeConfig(BaseModel):
     github_adapter: str
     discord_adapter: str
     storage_adapter: str
+    # When false, skip score computation/upsert (ingestion and notifications still run).
+    enable_scoring: bool = True
+    # When false, skip applying Discord role add/remove (notifications unaffected).
+    enable_discord_role_updates: bool = True
 
     @field_validator("log_level")
     @classmethod