Open Source Project Manager — Customization Guide

How to adapt the system for your project's size, governance model, and tooling.

Table of Contents

1. Solo Maintainer Setup

2. Multi-Repository Projects

3. Governance Models

4. Integrating with GitHub / GitLab

5. Community Engagement Tracking

6. Custom Label Taxonomies

7. Sponsorship & Funding Tracking

8. Scaling to a Large Maintainer Team

Solo Maintainer Setup

If you're the only maintainer, strip the system down to essentials:

Keep these databases:

• Issues (your primary tracker)
• Contributions (track incoming PRs)
• Releases (plan and document releases)

Skip or defer:

• Contributors (you know who you are; add this when you get repeat contributors)
• Roadmap (use a simple checklist on your dashboard instead)

Simplify statuses:

• Issues: Open → In Progress → Closed
• Contributions: Open → Merged / Closed
• Releases: Planning → Published

Time-saving tip: Use the Issues database as your single inbox. Add a "Type" filter to switch between bugs, features, and tasks. Skip the triage ceremony — just sort by Priority and work top-down.

Multi-Repository Projects

If your project spans multiple repositories (e.g., a core library, a CLI tool, documentation site, and SDK):

Option A: Single System with Repository Tags

1. Add a "Repository" Select property to both Issues and Contributions databases.

2. Options: core-lib, cli-tool, docs-site, typescript-sdk, etc.

3. Create filtered views per repository on each database.

4. The Contributors and Releases databases stay shared across all repos.

Pros: Single source of truth. Easy cross-repo queries. One dashboard.

Cons: Database gets large. Hard to set per-repo permissions.

Option B: Duplicate Per Repository

1. Create a separate workspace page per repository.

2. Duplicate the full system for each repo (Issues, Contributions, Releases).

3. Keep a single shared Contributors database at the top level.

4. Add cross-repo relations for Contributors.

Pros: Clean separation. Per-repo permissions. Independent release cycles.

Cons: Harder to see the big picture. Duplicate maintenance.

Recommendation: Start with Option A. Split to Option B when you exceed ~200 total issues or have repos with independent release cycles.

Governance Models

BDFL (Benevolent Dictator for Life)

• Default setup. One maintainer has final say on all decisions.
• Customize: Remove "Votes" from issue priority calculation. Add a "Maintainer Decision" Select property (Approved / Rejected / Needs Discussion).
• The maintainer reviews the PR Pipeline board daily and makes merge decisions.

Consensus-Based

• All core contributors must agree on major decisions.
• Add a "Approval Votes" Number property to Issues and Contributions.
• Add a "Approvers" Multi-select or Relation property listing who approved.
• Create a formula: if(prop("Approval Votes") >= 3, "Approved", "Needs Votes").
• Add a "Decision" view filtered to items needing consensus.

Committee / TSC (Technical Steering Committee)

• Formal governance with a committee.
• Create a separate "Decisions" database with: Title, Proposal, Status (Proposed / Voting / Accepted / Rejected), Vote Count, Committee Members.
• Link Decisions ↔ Issues and Decisions ↔ Roadmap items.
• Use for RFCs, architectural decisions, and breaking changes.

Tiered Access

• Map contributor roles to permissions:

Integrating with GitHub / GitLab

Manual Sync (Recommended Starting Point)

1. Add a "GitHub URL" URL property to Issues and Contributions databases.

2. Copy the GitHub issue/PR link when creating the Notion entry.

3. Update status manually when it changes on GitHub.

4. Time cost: ~2 minutes per issue/PR. Acceptable for projects with <50 active items.

Automated Sync (GitHub → Notion)

Use GitHub webhooks + a small server to sync automatically:

Trigger events to sync:

• issues.opened → Create a new entry in Notion Issues database
• issues.closed → Update Status to "Closed" in Notion
• pull_request.opened → Create entry in Contributions database
• pull_request.merged → Update Status to "Merged"
• pull_request.review_submitted → Update review count

Field mapping:

Zapier / Make.com Integration

For a no-code approach:

1. Zapier trigger: "New Issue in GitHub Repository"

2. Zapier action: "Create Database Item in Notion"

3. Map fields as above.

4. Create separate Zaps for issues, PRs, and status changes.

Community Engagement Tracking

Add these properties to track community health beyond code contributions:

On the Contributors Database

Community Score Formula:

prop("Contributions") * 3 + prop("Forum Posts") * 1 + prop("Blog Posts") * 5 + prop("Conference Talks") * 10

New Database: "Community Events"

If your project has meetups, office hours, or conference presence:

Custom Label Taxonomies

By Project Type

Web Framework:

area/routing, area/middleware, area/templating, area/auth, area/database, area/websocket

CLI Tool:

area/parser, area/output, area/config, area/plugins, area/completion

Library:

area/core, area/types, area/utils, area/compat, area/extensions

By Workflow

Sponsorship & Funding Tracking

If your project receives sponsorships or funding, add a "Sponsors" database:

Sponsorship Dashboard Metrics:

• Monthly recurring revenue (sum of active sponsor amounts)
• Sponsor retention rate (active / total ever)
• Revenue by tier (bar chart view)
• Sponsor tenure (average months active)

Link sponsor funds to roadmap items with a "Funded By" relation to show which features are sponsor-driven.

Scaling to a Large Maintainer Team

5-10 Maintainers

• Assign area owners. Use the "Category" property on Roadmap and the Labels on Issues to assign ownership areas.
• Rotate triage duty. Add a "Triage Lead" rotation — one person per week handles incoming issues.
• Weekly sync meeting. Use the Project Dashboard as the meeting agenda. Review: new issues, stuck PRs, release timeline, roadmap progress.

10-20 Maintainers

• Create sub-teams. API team, Core team, Docs team, Infrastructure team. Each sub-team has its own filtered views.
• Add a "Team" Select property to Issues, Contributions, and Roadmap.
• Monthly planning meetings. Use the Roadmap board for quarterly planning. Each team proposes their items.

20+ Maintainers

• Governance formalization. Add a Decisions database. Require RFCs for all significant changes. Use voting for contested decisions.
• Metrics tracking. Add a "Project Metrics" database tracking weekly snapshots: open issues, PR backlog, contributor count, time-to-first-review.
• Separate workspaces. Consider splitting into per-team Notion workspaces with shared databases for cross-team items.

Tips for Long-Term Success

1. Review your "Good First Issues" list monthly. If it's empty, new contributors have no on-ramp. Intentionally create beginner-friendly issues.

2. Track time-to-first-review. Slow review times kill contributor motivation. Target <24 hours for first-time contributors, <48 hours for regulars.

3. Archive closed issues quarterly. Move issues closed >90 days ago to an archive database. Keeps your active databases fast.

4. Celebrate milestones. When a contributor reaches a new level (New → Regular → Core), acknowledge it publicly. Community recognition drives retention.

5. Keep the Contribution Guide updated. Review pages/contribution-guide.md every release. Outdated contribution guides are the #1 source of frustrated contributors.

*Questions? Contact [email protected]*