Projects Module
Project overview, docs, contributors, issues/PRs, and releases
A Project row (githubOwner + githubRepo, unique) represents one tracked open-source
project. Register one with:
pnpm --filter @olgax/github run add-project -- --owner=OLGAX-com --repo=olgax-posWhat's synced vs. fetched live
| Data | Source |
|---|---|
| Repo metadata (stars, language, homepage) | Synced into Project |
| Issues & pull requests | Synced into GithubIssue (a PR is an issue with isPullRequest/isMerged) |
| Reviews | Synced into GithubReview |
| Releases | Synced into GithubRelease |
| README | Fetched live via getReadme() — never persisted |
docs/ folder pages | Fetched live via listDocsPages() + getDocPage() — never persisted |
| Contributors list | Fetched live via getContributors() — never persisted |
Fetching docs and contributors live (rather than syncing them) means they can never drift out of sync with the real repository, at the cost of one extra GitHub API call per page view.
A project's full docs/ folder (flat, one level deep) renders at /projects/[slug]/docs and
/projects/[slug]/docs/[page] in the main app - see Projects for a live index
of every tracked project's docs.
Maintainers
ProjectMaintainer links specific users to a project (distinct from the global MAINTAINER
role) — set via add-project [email protected].
Project Proposals
Anyone signed in can propose a brand-new project at /projects/proposals (title + description, plus
optional GitHub repo URL, comma-separated technologies, and a desired-impact note). A proposal is
private — visible only to the proposer and to platform MAINTAINER/ADMINISTRATOR users —
until it's reviewed. Maintainers can review inline right on the proposal's own page (an "Approve"/
"Decline with reason" panel appears there while PENDING), or from the bulk queue at
/projects/proposals/review:
- Approve — the proposal goes public on
/projects/proposals, opening it up for comments (ProjectProposalComment) and a "Join project" button (ProjectProposalInterest, one row per user, idempotent) so contributors can team up before any code exists. - Reject — requires a reason, which the proposer sees on their own proposal (never shown
publicly). A rejected proposal can be edited and resubmitted by its original proposer, which
sends it back to
PENDINGfor another review round.
We deliberately don't automate creating the actual GitHub repository — that stays a manual
maintainer action (pnpm --filter @olgax/github run add-project), consistent with "GitHub is the
source of truth for code." Once that real Project exists, a maintainer links it to the approved
proposal (ProjectProposal.linkedProjectId) from the review page, and the proposal page then
points everyone to the live project.