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 support@datanest.dev*

Open Source Project Manager — Notion Import Guide

Step-by-step instructions for importing and configuring the Open Source Project Manager in Notion.

Prerequisites

• A Notion account (Free plan works; Pro recommended for Timeline views and automations)
• A dedicated Notion workspace or page for your project
• The 5 CSV files from the databases/ folder
• 25-35 minutes for initial setup

Step 1: Create Your Workspace Page

1. In Notion, create a new page called "[Your Project Name] — Project Manager".

2. Add an icon (suggested: 🔧 or your project logo) and a cover image.

3. This page will be the parent container for all databases and sub-pages.

Step 2: Import the Databases

Import in this order so that relations can reference already-imported databases.

2.1 Import contributors.csv

1. Inside your workspace page, click "/" → "Import" → "CSV".

2. Select databases/contributors.csv.

3. Rename the database to "Contributors".

4. Set property types:

5. Select colors for Role:

• Maintainer → Red
• Core → Orange
• Regular → Blue
• Contributor → Green
• New Contributor → Light Green

6. Select colors for Status:

• Active → Green
• Onboarding → Blue
• Inactive → Yellow
• Emeritus → Gray

2.2 Import releases.csv

1. Import databases/releases.csv inside the workspace page.

2. Rename to "Releases".

3. Set property types:

4. Select colors for Status:

• Planning → Light Gray
• Development → Blue
• Code Freeze → Purple
• Testing → Yellow
• Published → Green
• Yanked → Red

5. Select colors for Type:

• Major → Red
• Minor → Blue
• Patch → Green
• Pre-release → Yellow

2.3 Import roadmap.csv

1. Import databases/roadmap.csv.

2. Rename to "Roadmap".

3. Set property types:

4. Select colors for Status:

• Proposed → Light Gray
• Accepted → Blue
• In Progress → Yellow
• Completed → Green
• Deferred → Red

5. Effort color coding:

• XS → Light Green
• S → Green
• M → Blue
• L → Orange
• XL → Red

2.4 Import issues.csv

1. Import databases/issues.csv.

2. Rename to "Issues".

3. Set property types:

4. Status colors:

• Open → Light Gray
• Triaged → Blue
• In Progress → Yellow
• In Review → Orange
• Closed → Green
• Won't Fix → Gray

5. Priority colors:

• Critical → Red
• High → Orange
• Medium → Yellow
• Low → Gray

2.5 Import contributions.csv

1. Import databases/contributions.csv.

2. Rename to "Contributions".

3. Set property types:

4. Status colors:

• Draft → Light Gray
• Open → Blue
• In Review → Yellow
• Changes Requested → Orange
• Approved → Light Green
• Merged → Green
• Closed → Red

5. CI Status colors:

• Passing → Green
• Failing → Red
• Pending → Yellow

Step 3: Create Relations Between Databases

3.1 Contributions → Contributors (Author)

1. Open the Contributions database.

2. Add a new Relation property → select "Contributors" → name it "Author (Linked)".

3. Link each contribution to its author.

4. Add another Relation to "Contributors" → name it "Reviewer (Linked)".

3.2 Contributions → Issues

1. Add a Relation property → select "Issues" → name it "Linked Issue (Linked)".

2. Link contributions to the issues they address.

3.3 Issues → Contributors (Assignee)

1. Open the Issues database.

2. Add a Relation to "Contributors" → name it "Assignee (Linked)".

3. Link each assigned issue to its assignee.

3.4 Roadmap → Releases

1. Open the Roadmap database.

2. Add a Relation to "Releases" → name it "Target Release (Linked)".

3. Link roadmap items to their target release.

3.5 Roadmap → Contributors (Owner)

1. Add a Relation to "Contributors" → name it "Owner (Linked)".

2. Link roadmap items to their owner.

3.6 Roadmap → Roadmap (Dependencies — Self-Relation)

1. Add a Relation to "Roadmap" (itself) → name it "Depends On".

2. This creates a self-referencing relation for dependency tracking.

3.7 Releases → Contributors (Release Manager)

1. Open the Releases database.

2. Add a Relation to "Contributors" → name it "Release Manager (Linked)".

Step 4: Add Rollup Properties

On the Contributors Database

1. "Total PRs" — Rollup on the Author relation from Contributions → Count all.

2. "Open PRs" — Rollup on Author relation → Count where Status NOT IN (Merged, Closed).

3. "Issues Assigned" — Rollup on the Assignee relation from Issues → Count all.

On the Releases Database

1. "Roadmap Items" — Rollup on the Target Release relation from Roadmap → Count all.

2. "Completed Items" — Rollup on Target Release → Count where Status = "Completed".

On the Issues Database

1. "PR Count" — Rollup on the Linked Issue relation from Contributions → Count all. Shows how many PRs address this issue.

Step 5: Set Up Views

Issues Database Views

5.1 Board — "Issue Triage"

• Group by: Status
• Filter: Status ≠ "Closed" AND Status ≠ "Won't Fix"
• Card preview: Priority, Labels, Votes

5.2 Table — "All Issues"

• Sort: Priority ascending, Votes descending
• Show: Issue ID, Title, Type, Priority, Status, Labels, Milestone, Votes

5.3 Table — "Good First Issues"

• Filter: Labels contains "good-first-issue" AND Status = "Open"
• Sort: Votes descending
• Purpose: Link this view in your CONTRIBUTING.md to help new contributors find work

5.4 Board — "By Milestone"

• Group by: Milestone
• Shows which issues are targeted for which release

Contributions Database Views

5.5 Board — "PR Pipeline"

• Group by: Status
• Columns: Draft → Open → In Review → Changes Requested → Approved → Merged
• Card preview: Author, CI Status, Linked Issue

5.6 Table — "Needs Review"

• Filter: Status = "Open" OR Status = "In Review"
• Sort: Created Date ascending (oldest first — FIFO review)

5.7 Calendar — "PR Timeline"

• Date property: Created Date
• Shows PR submission patterns over time

Releases Database Views

5.8 Table — "Release Pipeline"

• Sort: Target Date ascending
• Show: Version, Type, Status, Target Date, Blockers, Release Manager

5.9 Board — "Release Status"

• Group by: Status
• Visual overview of where each release stands

Contributors Database Views

5.10 Table — "Active Contributors"

• Filter: Status = "Active" OR Status = "Onboarding"
• Sort: Contributions descending

5.11 Board — "By Role"

• Group by: Role
• Shows the team structure at a glance

Roadmap Database Views

5.12 Board — "Quarterly Roadmap"

• Group by: Quarter
• Sub-group by: Status
• Card preview: Effort, Priority, Owner

5.13 Board — "By Category"

• Group by: Category
• Shows the distribution of work across Core, API, Infrastructure, etc.

Step 6: Create Dashboard and Reference Pages

1. Copy content from pages/project-dashboard.md → create a "Project Dashboard" page.

2. Copy content from pages/contribution-guide.md → create a "Contribution Guide" page.

3. Copy content from pages/release-playbook.md → create a "Release Playbook" page.

For each page, replace any database references with Linked Database Views pointing to your actual databases.

Step 7: Add Database Templates

1. Open the Issues database → New template → paste content from templates/issue-template.md.

2. Open the Releases database → New template → paste content from templates/release-checklist-template.md.

3. Create a standalone page for templates/contributor-onboarding-template.md — link it from the Contribution Guide.

Step 8: Add Formula Properties

See formulas/FORMULAS.md for complete formulas. Key formulas to add:

1. Issues: Priority Score, Issue Age

2. Contributions: PR Age, Is Stale

3. Releases: Release Readiness %, Days Until Release

4. Contributors: Contributor Level

5. Roadmap: Roadmap Progress %

Step 9: Final Checklist

• [ ] All 5 databases imported and renamed
• [ ] Relations created (7 relations total across databases)
• [ ] Rollup properties configured
• [ ] At least 3 views per database created
• [ ] Dashboard page with linked database views
• [ ] Contribution Guide and Release Playbook pages
• [ ] Templates added to Issues and Releases databases
• [ ] Formula properties added

Troubleshooting

Self-relation on Roadmap shows empty options: Make sure you're relating the Roadmap database to itself. Notion supports self-referencing relations — the dropdown should show items from the same database.

Rollups show "No results": Ensure the underlying relation has linked entries. Rollups compute over the related items; if nothing is linked, the result is empty.

CSV import creates text instead of Select: After import, click the property header → "Edit property" → change to Select. Notion will convert the text values into Select options.

*Need help? Contact support@datanest.dev*