feature-requests

Feature Requests: Agent Guide

This document covers how podkit manages feature requests across GitHub Discussions, documentation, and the backlog. Follow these instructions when creating, updating, or closing feature requests.

Overview

Feature requests live in three places that must stay in sync:

Location	Purpose	Audience
GitHub Discussions (Ideas category)	Public voting, comments, and status updates	Users and contributors
Documentation (docs/project/roadmap.md, callouts in other docs)	Communicates what's planned and links to discussions	Users reading the docs
Backlog tasks (Backlog.md)	Internal tracking, implementation plans, acceptance criteria	Developers

The GitHub Discussion is the source of truth for public-facing feature status. The roadmap doc page and the pinned Roadmap discussion (#17) are derived views. The backlog task tracks implementation details.

GitHub Discussions

Repository setup

• Discussions are enabled on jvgomg/podkit
• Ideas category is used for feature requests (supports upvoting)
• Announcements category contains the pinned Roadmap discussion (#17)

Creating a new feature discussion

Use the GitHub GraphQL API via the gh CLI. Shell escaping of the body is tricky — use a Python helper:

import subprocess, json

REPO_ID = "R_kgDORjcW4Q"
IDEAS_CAT = "DIC_kwDORjcW4c4C4Hnu"  # Ideas category
ANNOUNCE_CAT = "DIC_kwDORjcW4c4C4Hnr"  # Announcements category
QUERY = "mutation($input: CreateDiscussionInput!) { createDiscussion(input: $input) { discussion { number url } } }"

def create_discussion(title, body, category_id=IDEAS_CAT):
    payload = json.dumps({
        "query": QUERY,
        "variables": {"input": {
            "repositoryId": REPO_ID,
            "categoryId": category_id,
            "title": title,
            "body": body
        }}
    })
    result = subprocess.run(
        ["gh", "api", "graphql", "--input", "-", "--jq",
         '.data.createDiscussion.discussion | "\\(.number) \\(.url)"'],
        input=payload, capture_output=True, text=True
    )
    return result.stdout.strip()  # "42 https://github.com/jvgomg/podkit/discussions/42"