Skip to content

Idea Proposal Framework

This document outlines the standard process for proposing, documenting, and implementing new ideas within the Lyzer project.

1. Proposal Template

When proposing a new feature, architectural change, or significant enhancement, please use the following template:

# [Idea Title]

- Author: [Your GitHub Username]
- Email: [Your Email, if you feel comfortable sharing it]
- Date: [Date of proposal]
- Status: [Draft/Review/Approved/Rejected/In Progress/Done]
- Planned: [Yes/No]
- Milestone: [Milestone name if planned]

## Summary
A concise summary (2-3 sentences) of the proposed idea.

## Motivation
Why is this idea valuable? What problems does it solve? Who benefits?

## Detailed Description

A thorough explanation of the idea, including:

- Technical details
- Diagrams where applicable
- Basic mockups where applicable
- Implementation approach
- Any alternatives considered (where applicable)

## Requirements

- Functional requirements
- Non-functional requirements (performance, security, etc.)
- Dependencies on other systems/features

## Implementation Plan
- Step by step implementation plan
    - This can change as we learn more about the idea, just a starting point

## Risks and Concerns
Any potential issues or challenges that should be considered.

## Open Questions
List any aspects that need further clarification.

2. Review Process

All idea proposals should follow these review steps:

  1. Draft Creation: Author creates the proposal document following the template above
  2. Peer Review: Share with maintainers for initial feedback
  3. Refinement: Update based on initial feedback
  4. Approval: Receive formal approval from the maintainers
  5. Documentation: Finalize and integrate into project documentation
  6. Wait for next milestone planning: The idea will be considered for the next milestone

3. Documentation Standards

Directory Structure

Place the idea documentation in the appropriate directory:

  • /Docs/docs/proposals/ideas/ - For idea proposals

Formatting Guidelines

  • Use Markdown consistently
  • Include a clear title (H1) at the top of each document
  • Organize content with hierarchical headings (H2, H3, etc.)
  • Use bulleted lists for items without specific sequence
  • Use numbered lists for sequential steps
  • Include code blocks with appropriate language tags
  • Add diagrams when they clarify complex concepts (using Excalidraw or similar)

Images and Diagrams

  • Store images in the appropriate /Docs/docs/proposals/ideas/assets/ subdirectory
  • Use descriptive filenames for images
  • Use relative links for internal documentation references
  • Include descriptive link text (avoid "click here")
  • Verify all links work before committing
  • Include references to external resources when applicable

4. Integration with Development Process

Documentation should be integrated with our development process:

  1. Proposal First: Document ideas before implementation begins
  2. Update During Development: Revise documentation as implementation progresses
  3. Review Documentation: Include documentation review in PR process

Example Proposal

See Example Feature Proposal for a complete example following this framework.