[RFD]: Issue Creation Policy

[jvd10]

Decision Goal

Establish a clear policy for creating and managing GitHub issues across OpenCHAMI repositories, distinguishing between RFDs (roadmap repo), ADRs (community repo), and implementation issues (code repos).

Category

Process

Stakeholders / Affected Areas

teams, users

Decision Needed By

No response

Problem Statement

Currently, there's no formal policy governing where and how issues should be created across the OpenCHAMI organization's repository structure. This leads to:

• Confusion about whether to submit feature requests as issues in code repos vs. RFDs in roadmap repo
• Inconsistent issue types and missing ADR references for development task work
• Difficulty tracking the relationship between RFDs, ADRs, and implementation issues
• Unclear guidelines on when bugs vs. development tasks should be created in code repos
• No clear process for handling security vulnerabilities or community feature suggestions

Proposed Solution

Implement a repository-specific issue policy:

Roadmap Repository:

• RFDs submitted as issues for new feature proposals
• Discussion and approval process before conversion to ADRs

Community Repository:

• Stores ADRs converted from approved RFDs
• No direct issue creation (ADRs are documents, not issues)

Code Repositories:

• Four issue types: Bug, Development Task, Security Vulnerability, and Feature Request
• Bug issues: Can be opened anytime, may optionally reference related ADR/RFD
• Development Task issues: Must reference a specific ADR, treated as development tasks to implement approved decisions
• Security Vulnerability issues: Can be opened anytime, not required to be tied to an ADR, follow responsible disclosure practices
• Feature Request issues: Community suggestions for new features, may lead to RFD creation after review, not for approved work

Workflow:

1. New features → RFD in roadmap repo
2. Approved RFDs → ADR in community repo
3. Implementation work → Development Task issues in code repos referencing ADR
4. Bug reports → Bug issues in relevant code repos
5. Security issues → Security Vulnerability issues in relevant code repos
6. Community suggestions → Feature Request issues in code repos, may prompt RFD creation

Alternatives Considered

• Single repository for all issues: Rejected due to loss of service-specific context
• No ADR requirement for development tasks: Rejected as it breaks the RFD→ADR→implementation workflow
• Allow feature requests directly in code repos: Modified to allow as suggestions that may lead to RFDs
• More granular issue types: Rejected to keep code repo issues simple and focused
• Separate security reporting process: Considered but included as issue type for transparency while following disclosure practices

Other Considerations

Risks:

• Contributors may not understand the three-repo workflow initially
• Development Task issues without ADR references may slip through
• Bug vs. development task vs. feature request categorization ambiguity
• Security vulnerabilities may need special handling for sensitive issues

Trade-offs:

• Structured workflow vs. contributor learning curve
• Clear separation of concerns vs. potential overhead
• Transparency for security issues vs. responsible disclosure

Open Questions:

• How to handle bugs that reveal need for architectural changes?
• Should development task issues be automatically linked to their ADRs?
• What's the process for updating ADRs based on implementation feedback?
• Should feature requests have a standardized format for evaluation?
• How to handle private security vulnerability reporting?

Related Docs / PRs

• OpenCHAMI Roadmap Repository
• OpenCHAMI Community Repository

[alexlovelltroy]

Two additional proposed consequences:

• We should embed this policy in the issue template(s) and chooser.
• We should include organization-level automation to move non-bug issues out of individual repositories and into the right top level repo.

[alexlovelltroy]

@OpenCHAMI/tsc should comment further. I think this is exactly what we are aiming for and I'd like to figure out how to implement in such a way that new users and developers find it hard to make a mistake with our process.

[rainest]

Looking at the existing https://github.com/OpenCHAMI/.github/blob/b43ad03eec60e3eff98116585aaa9bdb7e2bec66/.github/ISSUE_TEMPLATE/development.md versus what's available from https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms it'd be nice to:

• Auto-assign bug reports to an org triage project.
• Stop using title templates as pseudo-labels.
• Maybe coalesce feature requests/RFDs to the general org Discussions feature.

We should include organization-level automation to move non-bug issues out of individual repositories and into the right top level repo.

This will actually fight Github's native local issue/PR logic a bit (writing #112 #112) auto-links to self

Keeping issues in the repo's fine if we apply:

projects: ["OpenCHAMI/NN"]
labels: ["something-the-project-automation-recognizes-TRIAGE"]

It'll funnel to a central project, we just need to create one.

[alexlovelltroy]

I think I can take a crack at this today. My understanding of what's needed is:

• Convert the existing issue templates from the .md format to the more advanced .yml format
• Add automatic labeling to the template(s)
• Reduce the number of templates to Bug and Feature
• Add automation to move labeled issues to the appropriate repository
• Add automation to mark bugs as stale and features as not-planned after a period of time (6 weeks?)
• Add a github project dashboard that includes all newly created bugs/feature requests
• Add a .md file to the community repo that describes the process above and ensure it is linked in the issue templates

We've tried to leverage discussions before and it didn't work. I'm open to exploring that again, but I'd like to leave that until later.

[alexlovelltroy]

Working on the automation in https://github.com/OpenCHAMI/.github/tree/governance/add-issue-automation

[rainest]

We've tried to leverage discussions before and it didn't work. I'm open to exploring that again, but I'd like to leave that until later.

What were the issues? Maybe a mix of standards track-ish stuff and general requests for assistance? Trying to be better about categories would maybe help. My expectation is that any OSS forum with a diverse set of participants is gonna have some level of stuff that's not categorized or submitted "correctly", and that's just something we'll have to live with.

Add automation to move labeled issues to the appropriate repository

What would end up moving from one repo to another? It'd maybe be easier to try to redirect wrong venue submissions/ask people to open something elsewhere, with a link to the original, or leave it up to maintainers to manually use the Transfer issue and Convert to discussion tools as they see fit.

The rest look reasonable.

[alexlovelltroy]

We need to clarify. Do we want feature requests to remain a part of the individual repo (smd/bss/etc...) or do we want them to automatically move to the roadmap repo where we can triage (and move back) as needed?

[rainest]

We need to clarify. Do we want feature requests to remain a part of the individual repo (smd/bss/etc...) or do we want them to automatically move to the roadmap repo where we can triage (and move back) as needed?

#117 (comment) is now edited to say keep them in one repo, but collect them in a shared project.

More edit, in new comment!: apparently Github makes this impossible natively for no good reason: https://github.com/orgs/community/discussions/47803

There is https://github.com/marketplace/actions/add-to-github-projects as a somewhat kludgy workaround, but that's probably viable enough if we can get https://docs.github.com/en/actions/how-tos/reuse-automations/create-workflow-templates working to point them to a common project quickly.

[rainest]

Indirectly related to this, any luck getting the workflow templating stuff working? I saw OpenCHAMI/.github#22 and a bunch of other activity there, but dunno if there was any success getting that to behave, so that we could then add a workflow to automatically add issues across repos to an org project.

[alexlovelltroy]

Continuing work on automation. Issues will be moved from repos and they will be added to project boards. We can review again after some testing

[rainest]

I know I've not kept with trying to POC it not moving across repos, but if you've gotten the project board stuff working, do you think we still need the issue moves as well?

My thinking with the boards is that they're the best of both worlds past the stupid native automation limitation (which is hopefully what got solved? IDK absent links to a PR)--projects can maintain ownership of issues that are single project scope, which is good.

The URLs showing something like and associated Github autoformatting is clearer at a glance:

• external issues do full URL (for example, https://github.com/OpenCHAMI/smd/issues/59 here looks like https://github.com/OpenCHAMI/smd/issues/59)
• local issues condense to shorthand (for example, the self-link https://github.com/OpenCHAMI/roadmap/issues/117 looks like [RFD]: Issue Creation Policy #117)

That's both familiar to Github users, obvious where an issue lives, and easily distinguishable at a glance. Putting everything in an umbrella org issue holder repo (https://github.com/OpenCHAMI/roadmap/issues/ maybe) requires you click through to see what the issue's about.

Centralized issue repos are good for holding things that cut across repos (e.g. #113, for "HTTP framework across all services), but not for something like OpenCHAMI/bss#29 that's only relevant to BSS. I'm not clear on whether we're saying "automatically move everything to central repo" (probably a bad idea) or "manually move cross-project issues if someone accidentally creates them in a single service repo" (that's fine and dandy).