Skip to content

README.md

Latest commit

 

History

History
159 lines (116 loc) · 5.92 KB

README.md

File metadata and controls

159 lines (116 loc) · 5.92 KB
Raw

Open-ADR

image

Status: Experimental

Deploy with Vercel

What is it?

Open-ADR is a web app to discover, author, and review Architecture Decision Records (ADRs) across GitHub repositories.

  • Browse public repositories without signing in (higher limits with a server token).
    Explore page: /explore (deep‑link: /explore?owner=<o>&repo=<r>)
  • Detects common ADR folder conventions and can auto-discover ADRs if paths aren’t standard.
  • Lists ADRs and parses YAML front‑matter status: (normalized to common values).
  • Views ADR markdown directly from GitHub.
  • Creates new ADRs as pull requests — sign in, review/merge on GitHub. With write access the branch lives in the repo; without it, the proposal is built in your fork and comes back as a normal PR.
  • Edits and supersedes ADRs as pull requests too — superseding updates the old ADR's status: superseded by NNNN in the same PR.
  • Shows open ADR PRs as proposals with the ADR file preview from the PR branch, inline line comments, threaded replies, and approvals.
  • Approve proposals in-app; once reviewed, set the ADR's status (accepted / rejected / deprecated) directly from the proposal view.

Quick start (local)

  1. Clone and install
git clone https://github.com/seluard/open-adr.git
cd open-adr
npm install
  1. Configure .env.local
GITHUB_ID=your_client_id
GITHUB_SECRET=your_client_secret
NEXTAUTH_SECRET=generate_a_long_random_string
NEXTAUTH_URL=http://localhost:3000
# Optional – improves rate limits for public browsing
GITHUB_PUBLIC_TOKEN=your_server_token
# Optional – landing demo buttons
NEXT_PUBLIC_DEMO_REPOS=owner1/repo1,owner2/repo2
# Optional – navbar repo+stars (defaults to this repo)
NEXT_PUBLIC_REPO_OWNER=seluard
NEXT_PUBLIC_REPO_NAME=open-adr

Generate a secret (example):

openssl rand -base64 48
  1. Run the dev server
npm run dev

Visit http://localhost:3000

  • Browse public repos without signing in at /explore.
  • Sign in with GitHub for private repos and higher rate limits.

Deploy to Vercel

  • Use the button above or: https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fseluard%2Fopen-adr
  • Set environment variables:
    • GITHUB_ID, GITHUB_SECRET, NEXTAUTH_SECRET, NEXTAUTH_URL
    • Optional: GITHUB_PUBLIC_TOKEN (raises public rate limits)
    • Optional: NEXT_PUBLIC_DEMO_REPOS
    • Optional: NEXT_PUBLIC_REPO_OWNER / NEXT_PUBLIC_REPO_NAME
  • In your GitHub OAuth App, set the callback URL to: https://<your-project>.vercel.app/api/auth/callback/github.

Environment variables (summary)

  • GITHUB_ID / GITHUB_SECRET – GitHub OAuth App credentials
  • NEXTAUTH_SECRET – long random string for sessions/JWT
  • NEXTAUTH_URL – absolute app URL (important in deploys)
  • GITHUB_PUBLIC_TOKEN (optional) – server-side token for public browsing rate limits
  • NEXT_PUBLIC_DEMO_REPOS (optional) – comma‑separated demo repos for landing buttons
  • NEXT_PUBLIC_REPO_OWNER / NEXT_PUBLIC_REPO_NAME (optional) – controls repo+stars in navbar

Supported folder conventions

Folder Example Notes
docs/adr/ docs/adr/0001-first-decision.md Preferred if you keep docs grouped
doc/adr/ doc/adr/0001-first-decision.md Variant seen in some repos
docs/decisions/ docs/decisions/0002-something.md Common alternate
doc/decisions/ doc/decisions/0002-something.md Variant seen in some repos
docs/architecture/decisions/ docs/architecture/decisions/0003.md Popular long path
architecture/decisions/ architecture/decisions/0003.md Alternate
adr/ adr/0004-final.md Common alternate
adrs/ adrs/0004-final.md Alternate
decisions/ decisions/0004-final.md Alternate

If none of the above match, Open‑ADR will attempt a lightweight default-branch tree scan to locate ADR files.

Example ADR front‑matter

---
status: accepted
date: 2025-09-11
---

Unrecognized values are shown as unknown (for now).

Roadmap

Done

  • Shared front-matter parser (single source of truth)
  • Caching layer to reduce GitHub rate-limit hits
  • Unified error handling, dead routes removed
  • Create ADRs via PR from the UI (sign in; contributors without push access fall back to a fork-and-PR flow)
  • Edit ADRs via PR from the UI
  • Supersede an ADR with a new one in a single PR (old ADR's status updated automatically)
  • PR merge = acceptance (read-time status resolution)
  • Open ADR PRs listed as proposals, with ADR file preview from the PR branch, inline line comments, threaded replies, and approvals
  • Set an ADR's status (accepted / rejected / deprecated) from a reviewed proposal — written to the file via a PR-branch commit, so it is correct outside Open-ADR too

Next

  • Authoring & lifecycle (remaining)
    • Multi-line comment ranges
  • Org awareness
    • Org dashboard: ADR counts, status distribution, superseded rate
    • Cross-repo search over a cached index
    • Saved repo collections / multi-repo views
    • GitHub Enterprise / SSO auth

Decisions and reasoning: see docs/adr/.

Contributing

Early stage. Please open an issue describing the idea/problem before a PR.

License

MIT – see LICENSE

MIT was chosen deliberately: maximum adoption and contribution-friendliness, no copyleft or dual-license split. This is a community-first project.

FAQ

  • Editing existing ADRs? Yes — edits and supersessions go through pull requests, reviewed and merged on GitHub.
  • Will you support GitLab? Possibly later; GitHub first.
  • Does it store ADRs? No, it fetches from GitHub on demand.
  • Rate limits? The app returns 429 when GitHub rate limits are exceeded; set GITHUB_PUBLIC_TOKEN to improve public browsing.

If this project is useful, please star the repository – it helps prioritize the roadmap.