# Contributing Guidelines

This document establishes guidelines for using GitHub Discussions and Issues for technical conversations about the Agent Manager.

## Getting Started[​](#getting-started "Direct link to Getting Started")

* Discussions, issues, feature ideas, bug reports, and design proposals from the community are welcome
* For security vulnerabilities, please report to <security@wso2.com> as per the [WSO2 Security Reporting Guidelines](https://security.docs.wso2.com/en/latest/security-reporting/report-security-issues/)

## Discussion Categories[​](#discussion-categories "Direct link to Discussion Categories")

| Category             | Purpose                               | Example Topics                                                     |
| -------------------- | ------------------------------------- | ------------------------------------------------------------------ |
| **Announcements**    | Official updates from maintainers     | Releases, roadmap updates, breaking changes                        |
| **General**          | Open-ended conversations              | Community introductions, general questions                         |
| **Ideas**            | Feature suggestions and brainstorming | New capabilities, integration ideas                                |
| **Q\&A**             | Technical questions with answers      | Implementation help, troubleshooting                               |
| **Show and Tell**    | Share projects and integrations       | Agent implementations, use cases                                   |
| **Design Proposals** | Technical design discussions          | Architecture changes, system design, new features requiring review |

## When to Use Discussions vs Issues[​](#when-to-use-discussions-vs-issues "Direct link to When to Use Discussions vs Issues")

| Use Discussions For             | Use Issues For                             |
| ------------------------------- | ------------------------------------------ |
| Open-ended questions            | Bug reports with reproduction steps        |
| Feature ideas and brainstorming | Concrete feature requests with clear scope |
| Design proposals and RFCs       | Actionable tasks and work items            |
| Community engagement            | Pull request discussions                   |
| Troubleshooting help            | Security vulnerabilities (private)         |

## Guidelines[​](#guidelines "Direct link to Guidelines")

### Starting a Discussion[​](#starting-a-discussion "Direct link to Starting a Discussion")

1. **Search first** - Check existing discussions to avoid duplicates
2. **Choose the right category** - Use the category table above
3. **Use a clear title** - Be specific and descriptive
4. **Provide context** - Include relevant details, code snippets, or diagrams

### Promoting Discussions to Issues[​](#promoting-discussions-to-issues "Direct link to Promoting Discussions to Issues")

When a discussion results in actionable work:

1. Summarize the outcome in a final comment
2. Create a linked GitHub Issue for implementation
3. Reference the discussion in the issue for context

## Feature Lifecycle[​](#feature-lifecycle "Direct link to Feature Lifecycle")

Features progress through distinct stages from initial concept to implementation:

### 1. Idea Stage[​](#1-idea-stage "Direct link to 1. Idea Stage")

High-level discussions about capabilities we want to explore start in the **Ideas** category. These are similar to epics—broad in scope with no imposed structure. Ideas allow open brainstorming before committing to specific solutions.

### 2. Design Proposal Stage[​](#2-design-proposal-stage "Direct link to 2. Design Proposal Stage")

When an idea is refined into a well-scoped feature, create a discussion in the **Design Proposals** category. Proposals must follow the standard template:

| Section                     | Description                                                                                                                |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Problem**                 | Describe the problem, who is affected, and the impact                                                                      |
| **User Stories**            | Define user stories using the format "As a \[role], I want \[goal] so that \[benefit]"                                     |
| **Existing Solutions**      | How is this solved elsewhere? Include current workarounds and links to relevant implementations, docs, or design proposals |
| **Proposed Solution**       | Technical approach and design details                                                                                      |
| **Alternatives Considered** | What other approaches were evaluated?                                                                                      |
| **Open Questions**          | Unresolved technical decisions that need input (if any)                                                                    |
| **Milestone Plan**          | Implementation phases aligned with release milestones                                                                      |

#### Proposal Labels[​](#proposal-labels "Direct link to Proposal Labels")

Use these labels to track design proposal status:

| Label                  | Description                               |
| ---------------------- | ----------------------------------------- |
| `Proposal/Draft`       | Initial proposal, still being written     |
| `Proposal/Review`      | Ready for team review and feedback        |
| `Proposal/Approved`    | Design accepted, ready for implementation |
| `Proposal/Rejected`    | Proposal declined                         |
| `Proposal/Implemented` | Design fully implemented                  |

### 3. Implementation Tracking[​](#3-implementation-tracking "Direct link to 3. Implementation Tracking")

Once a design proposal is approved:

1. Create GitHub Issues for implementation tasks
2. Link issues back to the design proposal discussion
3. Assign issues to appropriate milestones
4. Track progress through milestone completion