RFC: Contributor profile editing from leaderboard (GitHub edit link, copy markdown, optional issue-driven bot)

[rithviknishad]

Summary

Explore ways to let contributors update their profile (contributors/{username}.md in the data repo) from the leaderboard web app, without embedding org GitHub PATs or calling GitHub APIs from the static site.

Context

• Data repo URL is available as leaderboard.data_source (e.g. https://github.com/ohcnetwork/leaderboard-data).
• Example profile file: https://github.com/ohcnetwork/leaderboard-data/blob/production/contributors/rithviknishad.md.
• Next.js app is static export; build-time data comes from LibSQL.

Option A: Deep link to GitHub file editor + clipboard

Edit URL (when repo + branch are known):

https://github.com/{owner}/{repo}/edit/{branch}/contributors/{username}.md

Gap: data_source is only the repo URL today. We likely need an optional config field (e.g. leaderboard.data_branch, default main) because many orgs use non-default branches (e.g. production).

Pre-filling the editor via URL: GitHub does not document supported query parameters to inject file body content on the /edit/... page (unlike issues/PRs). Community threads exist; this is not a reliable product surface.

Practical UX without API:

1. Edit on GitHub → opens the web editor for that path.
2. Copy profile as Markdown → build YAML frontmatter + body from DB fields (Contributor type: username, name, role, title, avatar_url, social_profiles, joining_date, meta, bio) using js-yaml, user pastes into GitHub.
3. Optional: For public repos, browser fetch of raw.githubusercontent.com/.../contributors/{username}.md for byte-accurate "copy current file" (best-effort; private repos need another path).

Fidelity: Reconstructing from DB may drop YAML keys/comments never stored in the DB.

Option B: Form → prefilled GitHub issue → Actions “rolling PR” (changesets-style)

Flow:

1. Leaderboard hosts a form; submit opens Create issue with title / body query params (supported by GitHub).
2. Body uses a strict, versioned format (e.g. fenced YAML/JSON) the workflow parses.
3. Workflow in the data repo (where markdown lives) on issues: opened (or on label after review):
   • Validates payload; comments on failure.
   • Maintains one open integration PR until merged; new issues add commits to the same branch.
   • Commits / PR description use Fixes #123 so issues close when the PR merges.

Strengths: Guided UX, audit trail, no PAT on the static site; uses GITHUB_TOKEN in Actions.

Design risks to address:

• Authorization: Public issues must not allow arbitrary edits to any profile. Mitigations: only process if issue author matches profile username, and/or require maintainer label (e.g. profile-update-approved), etc.
• Concurrency: Two issues editing the same contributors/{user}.md need a defined rule (last wins, reject, queue).
• Branch hygiene: Long-lived PR may need merging main in periodically; define reset after merge.

Permissions: Workflow needs appropriate contents, pull-requests, and possibly issues scopes in the data repo.

Recommendation

• Ship Option A as low-friction (link + copy + optional raw copy) with data_branch config.
• Consider Option B for contributor-friendly submissions and maintainer-controlled batching, possibly alongside Option A for power users.

References

• GitHub: Editing files
• Community: Prefilling create/edit file via URL (not officially supported for editor body)

---

Discussion consolidated from internal design chat; implementation TBD.

[rithviknishad]

Detailed design: issue-driven profile updates with a rolling PR (changesets-style)

This expands on Option B from the issue description: a form on the leaderboard that opens a new GitHub issue with a structured title/body, and automation in the data repository that turns those issues into commits on one long-lived pull request until that PR is merged.

---

End-to-end flow

1. Leaderboard (static site)

   • Contributor opens something like “Request profile update” on their profile page.
   • They fill a form (name, title, bio, socials, etc.—whatever we choose to support).
   • Submit does not call GitHub’s API. It navigates to (or opens) GitHub’s new issue URL with query parameters, e.g. title= and body=, which GitHub officially supports for issues.
   • The body is a machine-readable block we define (see below), plus optional human-readable context.

2. Data repo (e.g. leaderboard-data)

   • A GitHub Actions workflow runs when a relevant issue is opened (or when a label is applied—see trade-offs).
   • The workflow parses the issue body, validates the payload, and either:
     • applies updates to contributors/{username}.md on a dedicated branch, or
     • posts a comment explaining validation errors and stops.
   • It pushes commits and ensures there is an open PR from that integration branch into the default data branch.
   • New issues that pass validation result in additional commits on the same branch / same open PR, until that PR is merged—similar in workflow shape to how Changesets keeps amending a “Version Packages” PR until you merge it.

3. Merge and cleanup

   • Commit messages and/or the PR description should include Fixes #123 / Closes #123 (and multiple issue numbers if one commit addresses several) so GitHub auto-closes those issues when the PR merges.
   • After merge, the next qualifying issue creates a new integration branch (or reuses a naming convention) and a new PR.

---

Payload format (suggested properties)

• Versioned schema, e.g. profileUpdateVersion: 1 in a fenced YAML or JSON block, so parsers can evolve without breaking old issues.
• Explicit username (or GitHub login) the change applies to—must be consistent with authorization rules.
• Fields aligned with contributor frontmatter + body: name, role, title, avatar_url, social_profiles, joining_date, meta, bio (markdown), etc.
• Strict validation: required keys, allowed roles (must match config.yaml in data repo), URL shapes, max lengths—mirror what the importer / org expects.

Malformed or malicious bodies should never write to the repo; the bot should comment with a clear error.

---

Authorization and trust (critical trade-off)

Problem: On a public repo, anyone can open an issue claiming “update alice’s profile.” Without checks, the bot is remote code/config editing by unauthenticated strangers.

Mitigations (pick at least one; combining is stronger):

Approach	Pros	Cons
Issue author must equal profile username (for GitHub-backed usernames)	Simple; no maintainer bottleneck for honest contributors	Spoofing GitHub identity is not the issue—GitHub already binds the author; still need to ensure username in payload matches author login
Maintainer label required (e.g. profile-update-approved) before workflow runs	Strong gate; blocks drive-by spam	Slower; not self-serve
CODEOWNERS / required review on PR	Human review before merge	Doesn’t stop bad commits on the bot branch unless combined with review
Allowlist / org members only	Reduces abuse	Excludes external contributors unless listed

Recommendation: At minimum, verify that the parsed username matches github.event.issue.user.login (when profiles are 1:1 with GitHub logins). If your leaderboard usernames can diverge from GitHub login, you need an explicit mapping or maintainer approval.

---

Concurrency and conflicts

Problem: Two issues both update contributors/alice.md while the same rolling PR is open.

Options:

• Last writer wins (simplest; predictable but can silently drop an earlier issue’s intent).
• Reject the second with a bot comment (“open a new issue after PR #N merges” or “conflict with pending change in #N”).
• Serialize via a queue (heavier; usually unnecessary at small scale).

Document the chosen rule in the workflow README so contributors know what to expect.

---

Branch and PR lifecycle

• Naming: e.g. bot/profile-updates or chore/profile-updates-2026Q1—predictable for automation.
• If no open PR from that branch: create branch from default, apply commit(s), open PR.
• If PR already open: fetch branch, apply new commit(s), push—PR updates automatically.
• Drift: If the integration branch is old, merging default back into it (or rebasing) reduces merge conflicts at final merge time—same class of problem as long-lived Changesets PRs.
• After merge: Reset state so the next issue starts from a fresh branch off the new default tip (or use a new branch name per “batch”).

---

Comparison to Option A (edit link + copy markdown)

	Option A (edit + paste)	Option B (issue + bot PR)
Implementation on leaderboard	Link + optional copy / raw fetch	Form + encode issue body URL
GitHub API / PAT on site	None	None
Writes to git	Human commits via GitHub UI	Actions + GITHUB_TOKEN in data repo
Contributor UX	Must use editor; paste step	Structured form → issue; bot does file edit
Maintainer load	Only review normal PRs if they use forks	Review one batched PR; can add labels/gates
Abuse surface	Normal GitHub permissions on data repo	Must design auth for issue-triggered writes

They are complementary: Option A suits power users; Option B suits guided, self-serve updates with centralized review.

---

Operational considerations

• Spam / noise: Rate limits, required labels, or templates can reduce junk issues.
• Workflow location: Automation must live in the repo that contains contributors/*.md, not necessarily in ohcnetwork/leaderboard.
• Secrets: Prefer GITHUB_TOKEN with least privilege; no org PAT on the static site.
• Observability: Bot comments (“Queued in PR #…”, “Failed: invalid role”) improve contributor experience.
• Testing: Dry-run mode or workflow_dispatch with a fixture issue body helps iterate safely.

---

Relation to Changesets

Similar: One integration PR accumulates multiple logical “requests” until merge; each new request amends that PR.

Different: Changesets usually touches disjoint package files; profile updates can collide on the same file (contributors/alice.md), so conflict policy matters more here.

---

Happy to split this into implementation tickets (leaderboard UI vs. data-repo workflow) when we pick this up.