Skip to content

Latest commit

 

History

History
622 lines (484 loc) · 14 KB

contributing.md

File metadata and controls

622 lines (484 loc) · 14 KB

Contributing to Rise

Thank you for your interest in contributing to Rise! This guide will help you get started whether you're fixing bugs, adding features, improving documentation, or creating plugins.

Project Status

Current Phase: Phase 3 (Code Generation & Preview) - ~95% complete
Next Phase: Phase 4 (Testing & Polish)
MVP Target: Schema Level 1 Only

Important: MVP focuses exclusively on Level 1 features. Level 2 and 3 features are deferred to post-MVP. Always check docs/SCHEMA_LEVELS.md before implementing anything.

Ways to Contribute

1. Code Contributions

Areas accepting contributions:

  • Bug fixes for existing features
  • Performance optimizations
  • Test coverage improvements
  • Documentation improvements
  • UI/UX enhancements (within Level 1 scope)

Not accepting yet:

  • Level 2 features (state, events, expressions)
  • Level 3 features (database, real-time)
  • Major architectural changes
  • Framework plugins (React only for MVP)

2. Documentation

Always welcome:

  • Fix typos and grammar
  • Clarify confusing sections
  • Add examples and tutorials
  • Improve API documentation
  • Create video guides

3. Bug Reports

How to report:

  1. Check existing issues first
  2. Include Rise version and OS
  3. Provide steps to reproduce
  4. Include error messages/logs
  5. Share minimal test case if possible

4. Feature Requests

Before requesting:

  1. Check docs/MVP_ROADMAP.md - it might be planned
  2. Verify it's not a Level 2/3 feature (post-MVP)
  3. Search existing issues

In your request:

  • Describe the problem you're solving
  • Explain the proposed solution
  • Consider implementation complexity
  • Note any breaking changes

Development Setup

Prerequisites

  • Node.js: v18.0.0 or higher
  • npm: v9.0.0 or higher
  • Git: For version control
  • Code Editor: VS Code recommended (with ESLint/Prettier extensions)
  • OS: macOS, Windows, or Linux

Initial Setup

  1. Fork and Clone:

    git clone https://github.com/YOUR_USERNAME/rise.git
cd rise

  2. Install Dependencies:

    npm install

  3. Run in Development:

    npm run dev

  4. Open Test Project:

    • File → New Project
    • Create a test project
    • Try creating components

Project Structure

rise/
├── src/
│   ├── main/              # Electron main process
│   │   ├── ai/           # AI component generation
│   │   ├── project/      # Project management
│   │   └── index.ts      # Main entry point
│   │
│   ├── renderer/          # Electron renderer (React UI)
│   │   ├── components/   # UI components
│   │   ├── hooks/        # React hooks
│   │   ├── stores/       # Zustand state stores
│   │   └── main.tsx      # Renderer entry
│   │
│   └── core/             # Core logic (used by both)
│       ├── manifest/     # Manifest management
│       ├── codegen/      # Code generation
│       ├── validation/   # Schema validation
│       ├── security/     # Security features
│       └── files/        # File system operations
│
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── fixtures/         # Test data
│
├── docs/                 # Documentation
├── .implementation/      # Task specifications
└── electron/             # Electron config

Development Workflow

  1. Pick an Issue:

    • Look for "good first issue" label
    • Comment to claim it
    • Get confirmation before starting

  2. Create Branch:

    git checkout -b fix/issue-description

  3. Make Changes:

    • Follow coding standards (see below)
    • Write tests for new code
    • Update documentation
    • Run linter and tests

  4. Commit:

    git add .
git commit -m "fix: description of what you fixed"

  5. Push and PR:

    git push origin fix/issue-description
    • Create Pull Request on GitHub
    • Fill out PR template
    • Link related issue

Coding Standards

TypeScript

Required:

  • Use TypeScript for all new code
  • Provide types for all function parameters and returns
  • Avoid any (use unknown if necessary)
  • Use interfaces for object shapes

Example:

// ✅ Good
interface GenerateOptions {
  incremental: boolean;
  verbose: boolean;
}

function generate(manifest: Manifest, options: GenerateOptions): GenerationResult {
  // implementation
}

// ❌ Bad
function generate(manifest, options): any {
  // implementation
}

Code Documentation

Requirements:

  • JSDoc comments on all public APIs
  • Inline comments for complex logic
  • README in each major directory

Comment Ratio: 1 comment per 3-5 lines of code

Example:

/**
 * Generate React code from component manifest
 * 
 * @param component - Component definition from manifest
 * @param manifest - Full manifest for context
 * @returns Generated React code as string
 * 
 * @example
 * const code = generator.generateComponent(comp, manifest);
 * // Returns: "import React from 'react'..."
 */
export function generateComponent(
  component: Component,
  manifest: Manifest
): string {
  // Build import statements for child components
  const imports = buildImports(component, manifest);
  
  // Generate props destructuring with defaults
  const props = buildProps(component);
  
  // Generate JSX element tree
  const jsx = buildJSX(component);
  
  // Combine and format
  return assembleCode(imports, props, jsx);
}

Testing Requirements

Unit Tests:

  • All core logic must have tests
  • Aim for >90% coverage
  • Use descriptive test names

Example:

describe('ReactCodeGenerator', () => {
  describe('generateComponent', () => {
    it('should generate valid React code for button component', () => {
      const component = createButtonComponent();
      const code = generator.generateComponent(component, manifest);
      
      expect(code).toContain('export function Button');
      expect(code).toContain('return <button');
      expect(code).toMatch(/className=["'].*["']/);
    });
    
    it('should throw error for invalid component', () => {
      const invalid = { id: 'test' };  // Missing required fields
      
      expect(() => {
        generator.generateComponent(invalid as Component, manifest);
      }).toThrow('Invalid component structure');
    });
  });
});

Running Tests:

npm test                 # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report
npm run test:unit       # Unit tests only

Code Style

Use ESLint and Prettier:

npm run lint           # Check for issues
npm run lint:fix       # Auto-fix issues

Key Rules:

  • No semicolons (Prettier removes them)
  • Single quotes for strings
  • 2-space indentation
  • Max line length: 100 characters
  • Trailing commas in multiline

File Organization

Naming Conventions:

  • Components: PascalCase.tsx
  • Utilities: camelCase.ts
  • Types: types.ts or ComponentName.types.ts
  • Tests: ComponentName.test.ts

Import Order:

// 1. External dependencies
import React from 'react';
import { someUtil } from 'external-lib';

// 2. Internal absolute imports
import { Component } from '@/core/manifest/types';
import { validate } from '@/core/validation';

// 3. Relative imports
import { helper } from './utils';
import type { LocalType } from './types';

Pull Request Process

Before Submitting

  • Code follows style guide
  • Tests added/updated
  • Tests pass locally
  • Documentation updated
  • No console.logs left in code
  • No commented-out code
  • Meaningful commit messages

PR Template

## Description
Brief description of what this PR does

## Related Issue
Fixes #123

## Type of Change
- [ ] Bug fix
- [ ] New feature (Level 1 only!)
- [ ] Documentation
- [ ] Performance improvement

## Testing
How did you test this?

## Screenshots (if applicable)
Before/after screenshots

## Checklist
- [ ] My code follows the style guide
- [ ] I have added tests
- [ ] All tests pass
- [ ] I have updated documentation
- [ ] No breaking changes

Review Process

  1. Automated Checks:

    • CI runs tests
    • Linter checks code
    • Build verification

  2. Human Review:

    • Core maintainer reviews code
    • May request changes
    • Discusses approach

  3. Approval & Merge:

    • Once approved, maintainer merges
    • Squash commits for clean history
    • PR automatically closes linked issues

Development Guidelines

Level 1 Boundaries

Always check before implementing:

Is this feature in Level 1?
    ↓ YES
Implement it!
    ↓ NO
Is it critical for MVP?
    ↓ YES
Discuss with maintainers first
    ↓ NO
Defer to Level 2/3 (post-MVP)

Level 1 Includes:

  • Static component properties
  • Component hierarchy
  • Props (parent → child)
  • Tailwind styling
  • Code generation
  • AI generation (basic)

Level 1 Excludes:

  • State management
  • Event handlers
  • Expressions
  • Computed properties
  • Custom logic
  • Database/API integration

Confidence Rating System

For complex changes, include confidence rating:

/**
 * @confidence 9/10 - Well-tested, follows established patterns
 * @concerns None identified
 */

Scale:

  • 10/10: Trivial change, impossible to break
  • 8-9/10: Well-understood, tested, confident
  • 6-7/10: Some complexity, edge cases considered
  • 4-5/10: Significant complexity, needs review
  • 1-3/10: Experimental, needs discussion

Below 8/10: Flag for mandatory human review

Security Considerations

Critical Code:

  • API key handling
  • File system operations
  • IPC communication
  • User input sanitization

Requirements:

  • Never log sensitive data
  • Validate all inputs
  • Use parameterized queries (future DB work)
  • Follow principle of least privilege

Performance Guidelines

Targets:

  • Code generation: < 100ms per component
  • UI interactions: < 16ms (60 FPS)
  • Manifest save: debounced 500ms
  • File watching: debounced 200ms

Optimization Techniques:

  • Use React.memo for expensive components
  • Debounce frequent operations
  • Virtual scrolling for large lists
  • Lazy loading of heavy dependencies

Working with AI (Cline)

Rise was built with heavy AI assistance. You can too!

Using Cline Effectively

  1. Read Task Specifications:

    • Check .implementation/ directory
    • Follow the detailed specifications
    • Reference related documentation

  2. Provide Context:

    I'm implementing Task 3.5 from the Phase 3 specification.

Current Context:
- We're in Phase 3 (Code Generation)
- Level 1 schema only
- ReactCodeGenerator already exists

Task: Add incremental generation support

Requirements:
[paste relevant requirements from task spec]

  3. Iterate on Output:

    • Review AI-generated code carefully
    • Test thoroughly
    • Refine based on results

  4. Document Decisions:

    • Add comments explaining why
    • Update relevant docs
    • Note in PR description

Common Tasks

Adding a New UI Component

  1. Create component file: src/renderer/components/MyComponent.tsx
  2. Define props interface
  3. Implement component with TypeScript
  4. Add to appropriate parent component
  5. Style with Tailwind
  6. Write tests: MyComponent.test.tsx
  7. Update documentation if public API

Adding to Core Logic

  1. Identify correct module (manifest, codegen, etc.)
  2. Create new file or extend existing
  3. Define TypeScript interfaces
  4. Implement with comprehensive comments
  5. Write unit tests (>90% coverage)
  6. Export from module index
  7. Update relevant documentation

Fixing a Bug

  1. Write failing test that reproduces bug
  2. Fix the code
  3. Verify test now passes
  4. Add regression test if needed
  5. Document fix in PR

Improving Performance

  1. Measure current performance
  2. Identify bottleneck
  3. Implement optimization
  4. Measure improvement
  5. Document benchmarks in PR

Release Process

For maintainers only:

  1. Version bump in package.json
  2. Update CHANGELOG.md
  3. Tag release: git tag v0.1.0
  4. Push tags: git push --tags
  5. Build release binaries
  6. Create GitHub release
  7. Announce to community

Communication

GitHub Issues

Use for:

  • Bug reports
  • Feature requests
  • Task tracking

Format:

  • Clear, descriptive title
  • Complete description
  • Steps to reproduce (bugs)
  • Expected vs actual behavior
  • Environment details

Discussions

Use for:

  • Questions about usage
  • Design discussions
  • RFC (Request for Comments)
  • Sharing projects built with Rise

Not for:

  • Bug reports (use Issues)
  • Support requests (use Issues with "question" label)

Code of Conduct

Our Standards

We are committed to:

  • Welcoming and inclusive environment
  • Respectful communication
  • Constructive feedback
  • Collaboration over competition

Unacceptable behavior:

  • Harassment or discrimination
  • Trolling or insulting comments
  • Personal attacks
  • Spam or self-promotion

Enforcement

Violations will result in:

  1. Warning
  2. Temporary ban
  3. Permanent ban

Report issues to project maintainers.

Getting Help

Stuck? Here's how to get help:

  1. Check Documentation:

    • Read relevant docs in /docs
    • Check examples in /tests/fixtures
    • Review task specifications in /.implementation

  2. Search Issues:

    • Someone may have had the same question
    • Check closed issues too

  3. Ask in Discussions:

    • Describe what you're trying to do
    • Share what you've tried
    • Include code snippets if relevant

  4. Pair Programming:

    • Maintainers occasionally available
    • Schedule through Discussions

Recognition

Contributors are recognized in:

  • CONTRIBUTORS.md file
  • Release notes
  • GitHub contributor graph

Significant contributions may result in:

  • Maintainer status
  • Project credits
  • Community shout-outs

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to Rise! Together we're building something special. 🚀