Discussions - Contribution Guidelines

[zanicar]

Discussions - Contribution Guidelines

Discussions welcomes all contributors.

This document serves as a guide for contributing to Discussions. It provides an overview of the processes and policies established for quality collaboration and coordination. Please familiarize yourself with these guidelines and feel free to propose changes to this document for improvement.

License

Important: All 3rd party contributions to this repository and to Discussions are made under the Apache License 2.0, unless otherwise agreed to in writing.

General Guidelines

Please follow these guidelines when creating a new topic or discussion.

For technical contributions to any particular repository, please refer to the contribution guidelines published in the repository. For example, see our general contribution guidelines.

Structure

A good discussion should contain the following elements:

Background

Provide a brief overview of the subject to set the stage and provide necessary context.

Rationale: Clearly state the value that could be added, utility that may be gained, or problem that could be addressed. Explain why this matters to the community.

Examples: Provide concrete, real-world examples that demonstrate the problem or opportunity. These help others understand the practical implications and identify similar experiences.

Scope: Indicate whether this affects developers, end-users, infrastructure, or other aspects of the ecosystem.

Question

Pose an open-ended question that invites community exploration rather than seeking validation of a predetermined solution.

Good question patterns:

• "How might we approach X while maintaining Y?"
• "What are the trade-offs between approach A and B?"
• "Has anyone encountered similar challenges with Z?"
• "What would an ideal solution look like for use case X?"

Avoid leading questions:

• "Shouldn't we implement feature X?" (implies preferred answer)
• "Why don't we just do Y?" (dismisses alternatives)
• "Is there any reason not to Z?" (creates defensive responses)

Research Integration: Reference current research, existing solutions, or related work to provide context without biasing the discussion toward a particular solution.

Examples

The following discussion and issue exemplify solicitation of open discussion respectively:

• Discussion: {Discussion_Example}
• Issue: {Issue_Example}

How Ideas Become Features

Discussions serve as the first step in our contribution pipeline. Here's how your ideas can evolve:

1. Discussion Phase (GitHub Discussions)

• Purpose: Gauge community interest and gather initial feedback
• Outcome: Consensus on whether idea merits formal proposal
• Duration: Typically 1-2 weeks for active discussions

2. RFC Phase (GitHub Discussions - Ideas)

• Trigger: Discussion shows significant community support
• Purpose: Technical exploration and feasibility assessment
• Content: More detailed technical approach and trade-offs
• Participants: Technical contributors and maintainers

3. Formal Proposal Phase (GitHub Issues)

• Trigger: RFC demonstrates technical viability
• Purpose: Detailed specification and implementation planning
• Process: Follows our Improvement Proposal Process
• Outcome: Accepted proposals become implementation epics

4. Implementation Phase (GitHub Projects)

• Trigger: Proposal acceptance by maintainers
• Process: Feature development following our development workflow
• Contribution: Community members can participate in implementation

Not every discussion becomes a feature, and that's perfectly fine! Discussions help us:

• Understand community needs
• Identify common pain points
• Build shared knowledge
• Strengthen the developer ecosystem

Discussion Quality Standards

Constructive Engagement

• Be Specific: Provide concrete examples and use cases
• Stay Focused: Keep discussions on-topic and relevant
• Be Respectful: Value diverse perspectives and experience levels
• Research First: Search existing discussions before creating duplicates

What Makes a Good Discussion

✅ Clear Problem Statement: What specific challenge are you addressing?

✅ Real-World Context: Why does this matter to developers/users?

✅ Open-Ended Questions: Invite community input rather than seeking validation

✅ Evidence-Based: Reference documentation, research, or examples

Discussion Red Flags

❌ Solution Seeking: "How do I implement X?" belongs in Q&A or Support

❌ Feature Requests: "Please add feature Y" should start as background + question

❌ Duplicate Topics: Search existing discussions first

❌ Vague Problems: "This is broken" without specific examples or context

When to Move Beyond Discussion

Consider creating an RFC when discussion shows:

• Strong community consensus on problem importance
• Multiple potential solution approaches identified
• Technical feasibility questions requiring deeper investigation
• Sufficient detail to begin formal specification

Community Moderation

Self-Moderation First

• Review your post before submitting
• Edit for clarity and conciseness
• Stay constructive even when disagreeing
• Help others by providing helpful links and context

Maintainer Moderation

Maintainers may take action when discussions:

• Become unproductive or off-topic
• Violate our code of conduct
• Duplicate existing active discussions
• Lack sufficient context for meaningful engagement

Moderation Actions

• Gentle Redirect: Guide discussions back on-topic
• Merge/Close: Consolidate duplicate discussions
• Archive: Preserve concluded discussions for reference
• Escalate: Serious conduct issues handled per our code of conduct

Appeals Process

If you believe moderation action was inappropriate:

1. Review the specific guideline cited
2. Contact the moderating maintainer directly
3. If unresolved, escalate to project leadership

Technical Detail Boundaries

Discussion-Appropriate Technical Detail

✅ High-Level Architecture: General approach and major components

✅ Trade-off Identification: Key decisions and their implications

✅ Integration Points: How it fits with existing systems

✅ Performance Implications: General scalability or efficiency concerns

RFC-Appropriate Technical Detail

🔄 Implementation Specifics: Detailed algorithms or data structures

🔄 API Specifications: Exact interface definitions

🔄 Protocol Details: Wire formats, message structures

🔄 Security Analysis: Threat models and mitigation strategies

When to Suggest Moving to RFC

If discussion comments include:

• Detailed technical specifications
• Multiple implementation approaches being debated
• Security or performance analysis requirements
• Questions requiring code examples or formal specification

Helpful transition phrase: "This is getting into RFC-level detail - should we consider moving this to a formal proposal?"

Discussion → IP Transition

Discussion Graduation Criteria

A discussion is ready for RFC/IP when it demonstrates:

• Clear problem definition with community consensus
• Sufficient engagement (minimum 5+ contributors commenting)
• Technical feasibility questions that need deeper investigation
• Alignment with project strategic direction (maintainer confirmation)

Transition Process

1. Community Member Triggers: Anyone can suggest moving to RFC
2. Maintainer Confirmation: Project maintainer confirms strategic fit
3. RFC Creation: Original poster or volunteer creates RFC in Ideas category
4. Discussion Reference: RFC links back to original discussion for context
5. Discussion Archive: Original discussion marked as "evolved to RFC"

Template for RFC Creation

When graduating from discussion, use this template:

RFC Title: [Clear, specific title]

Original Discussion: [Link to source discussion]

Problem Statement: [Refined based on discussion feedback]

Proposed Approach: [Technical direction emerging from discussion]

Open Questions: [Specific technical questions needing RFC-level investigation]

[muhammadumairabdulrehman]

Nice