Contributing - johnpeterman72/CursorRIPER GitHub Wiki

Contributing to CursorRIPER Framework

We welcome contributions to the CursorRIPER Framework! This page explains how to contribute effectively.

Getting Started

Prerequisites

Before contributing, make sure you have:

  • Cursor IDE installed
  • Git installed
  • Basic understanding of the framework
  • GitHub account

Development Setup

  1. Fork the Repository

  2. Clone Your Fork

    git clone https://github.com/YOUR-USERNAME/CursorRIPER.git
cd CursorRIPER

  3. Add Upstream Remote

    git remote add upstream https://github.com/johnpeterman72/CursorRIPER.git

  4. Create a Branch

    git checkout -b feature/your-feature-name

Development Workflow

Framework Structure

The framework consists of these main components:

CursorRIPER/
├── .cursor/
│   ├── rules/
│   │   ├── core.mdc          # Core framework definitions
│   │   ├── state.mdc         # State tracking
│   │   ├── start-phase.mdc   # Project initialization
│   │   ├── riper-workflow.mdc # Main workflow
│   │   └── customization.mdc # User preferences
│   └── cursorignore          # File exclusion patterns
├── memory-bank/              # Memory bank templates
│   ├── projectbrief.md
│   ├── systemPatterns.md
│   ├── techContext.md
│   ├── activeContext.md
│   └── progress.md
└── docs/                     # Documentation
    ├── setup-guide.md
    ├── workflow-guide.md
    └── memory-bank-guide.md

Making Changes

When making changes to the framework:

  1. Update Documentation

    • Ensure documentation reflects your changes
    • Update version numbers in affected files
    • Add comments explaining complex logic

  2. Follow Conventions

    • Use consistent formatting
    • Follow existing naming conventions
    • Maintain the established file structure

  3. Testing Changes

    • Test in a real project environment
    • Verify functionality in all modes
    • Test transitions between phases
    • Validate memory bank updates

Contribution Guidelines

Types of Contributions

We welcome these types of contributions:

  • Bug fixes: Addressing issues in the framework
  • Feature enhancements: Adding new capabilities
  • Documentation improvements: Making docs clearer or more complete
  • Example additions: Adding new usage examples
  • Workflow improvements: Enhancing the RIPER process

Contribution Process

  1. Find or Create an Issue

    • Check existing issues first
    • Create a new issue if none exists
    • Discuss approach before making significant changes

  2. Make Your Changes

    • Create a focused branch addressing one issue
    • Make minimal necessary changes
    • Add clear comments
    • Update version numbers and last_updated dates

  3. Submit a Pull Request

    • Push your changes to your fork
    • Create a pull request against the main repository
    • Reference the issue in your PR
    • Provide a clear description of changes

  4. Code Review

    • Respond to feedback
    • Make requested changes
    • Be patient during the review process

Pull Request Checklist

Before submitting a PR, check:

  • All framework files are consistent with each other
  • Documentation updated to reflect changes
  • Version numbers updated in changed files
  • Changes tested in a real project
  • All transitions and modes still work
  • Memory bank handling functions correctly
  • Issue referenced in PR description

Coding Standards

MDC File Standards

For MDC files (framework rules):

  1. YAML Frontmatter

    ---
description: "CursorRIPER Framework - Component"
globs: 
alwaysApply: true/false
version: "1.0.0"
date_created: "YYYY-MM-DD"
last_updated: "YYYY-MM-DD"
framework_component: "component_name"
priority: "critical/high/medium/low"
scope: "always_load/initialization/development_maintenance/optional"
---

  2. File Structure

    # Title - Version

## AI PROCESSING INSTRUCTIONS
[Instructions for AI]

## SECTION NAME
[Section content]

## ANOTHER SECTION
[Section content]

---

*Footer information*

  3. Version Numbering

    • MAJOR.MINOR.PATCH format
    • Increment PATCH for minor changes
    • Increment MINOR for feature additions
    • Increment MAJOR for breaking changes

Markdown Standards

For documentation and memory bank files:

  1. File Structure

    # Title
*Version: 1.0*
*Created: [DATE]*
*Last Updated: [DATE]*

## Section 1
Content

## Section 2
Content

---

*Footer information*

  2. Formatting

    • Use ATX headers (# for H1, ## for H2, etc.)
    • Use asterisks for emphasis (italic, bold)
    • Use backticks for inline code
    • Use fenced code blocks with language identifiers
    • Use lists with consistent indentation
    • Use consistent line breaks between sections

  3. Diagrams

    • Use Mermaid for diagrams
    • Include text descriptions for accessibility
    • Keep diagrams simple and focused

Development Guidelines

Framework Component Development

When creating or modifying framework components:

  1. Core Principles

    • Maintain mode separation
    • Ensure state consistency
    • Preserve safety protocols
    • Keep memory bank integrity

  2. Component Relations

    • Consider how components interact
    • Maintain dependency chain
    • Avoid circular dependencies
    • Document relationships

  3. Testing Strategy

    • Test with various project types
    • Test edge cases and transitions
    • Test with empty and populated memory banks
    • Test customization options

Documentation Development

When working on documentation:

  1. User Perspective

    • Write from user's perspective
    • Provide clear examples
    • Explain "why" along with "how"
    • Cover both basic and advanced usage

  2. Organization

    • Use consistent headers
    • Group related content
    • Provide navigation aids
    • Include cross-references

  3. Examples

    • Provide complete, working examples
    • Cover common use cases
    • Show context (not just isolated snippets)
    • Explain expected outcomes

Review Process

Review Criteria

Pull requests are reviewed based on:

  1. Functionality

    • Does it work as expected?
    • Does it maintain framework integrity?
    • Does it handle edge cases?

  2. Quality

    • Is the code clear and well-structured?
    • Is documentation complete and accurate?
    • Are standards followed consistently?

  3. Compatibility

    • Does it maintain backward compatibility?
    • Does it work with existing components?
    • Does it follow framework principles?

Review Timeline

  • Initial review typically within 1 week
  • Allow time for revisions and follow-up reviews
  • Final decision made after all issues addressed

Release Process

Version Numbering

The framework uses semantic versioning:

  • MAJOR.MINOR.PATCH
    • MAJOR: Breaking changes
    • MINOR: New features, non-breaking
    • PATCH: Bug fixes, minor improvements

Release Checklist

Before a new release:

  1. Update Version Numbers

    • Update in all affected files
    • Update in documentation

  2. Update Documentation

    • Add release notes
    • Update installation instructions
    • Update compatibility information

  3. Final Testing

    • Test upgrade from previous version
    • Test with various project types
    • Verify all modes and transitions

  4. Create Release

    • Tag version in git
    • Create GitHub release
    • Include detailed release notes

Communication

Where to Get Help

If you need help while contributing:

  1. GitHub Issues

    • Create a new issue with the "question" label
    • Be specific about what you're trying to do

  2. GitHub Discussions

    • Post in the Discussions tab for broader topics
    • Share ideas and get community feedback

  3. Documentation

    • Check existing documentation first
    • Reference specific sections in questions

Code of Conduct

We expect all contributors to:

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help maintain a welcoming community
  • Support new contributors

Recognition

Contributors are recognized in:

  1. Contributors List

    • Added to CONTRIBUTORS.md
    • Listed in GitHub repository

  2. Release Notes

    • Mentioned for significant contributions
    • Linked to merged pull requests

  3. Documentation

    • Acknowledged for documentation improvements
    • Credited for examples and guides

Thank you for contributing to the CursorRIPER Framework! Your efforts help make AI-assisted development more structured, safe, and effective.

CursorRIPER: Adaptive development, persistent intelligence.