Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
220 lines (166 loc) · 4.77 KB

CONTRIBUTING.md

File metadata and controls

220 lines (166 loc) · 4.77 KB

Contributing to @dreamfactory/create

Thanks for your interest in contributing! This guide will help you get started.

Quick Start

  1. Fork the repository

  2. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/create-dreamfactory.git
cd create-dreamfactory

  3. Install dependencies:

    npm install

  4. Build the project:

    npm run build

  5. Test locally:

    npm pack
# Creates @dreamfactory-create-X.Y.Z.tgz

# Test in a new directory:
cd /tmp
npm install /path/to/dreamfactory-create-X.Y.Z.tgz
npx create-dreamfactory test-project

Development Workflow

Project Structure

create-dreamfactory/
├── src/              # TypeScript source code
│   ├── cli.ts        # Main CLI orchestration
│   ├── prompts.ts    # User interaction
│   ├── generators/   # File generators
│   ├── setup/        # Docker & API setup
│   └── utils/        # Helper functions
├── templates/        # Files copied to user projects
│   ├── Dockerfile
│   ├── docker-compose.yml.template
│   ├── mcp-proxy/    # MCP daemon code
│   └── ...
├── docs/             # User documentation
└── tests/            # Test scripts

Making Changes

  1. Create a branch:

    git checkout -b feature/my-feature

  2. Make your changes in src/

  3. Build:

    npm run build

  4. Test:

    cd /tmp/test-area
node /path/to/create-dreamfactory/dist/index.js my-test --yes

  5. Commit:

    git add .
git commit -m "Add feature: description"

  6. Push & create PR:

    git push origin feature/my-feature

Good First Issues

Looking for something to work on?

Documentation

  • Improve README examples
  • Add more troubleshooting scenarios
  • Create video walkthrough transcripts
  • Translate docs to other languages

Templates (v0.3.0)

  • Design chatbot template schema
  • Create analytics dashboard template
  • Build e-commerce starter template

Testing

  • Test on different platforms (Mac, Windows, Linux)
  • Test with various databases
  • Performance testing

Connection Wizard (v0.2.0)

  • Database connection testing logic
  • Interactive prompts for credentials
  • Auto-configuration of DreamFactory services

Code Style

  • TypeScript: Use async/await, avoid callbacks
  • Formatting: Run npm run build (tsc handles formatting)
  • Naming: Descriptive function names (promptAdminEmail not getEmail)
  • Comments: Explain "why" not "what"

Example:

// ❌ Bad
async function getData() {
  const x = await fetch(url); // fetch data
  return x;
}

// ✅ Good
async function fetchDreamFactoryStatus(): Promise<EnvironmentResponse> {
  // Poll every 10s because DreamFactory takes 1-2min to initialize
  const response = await pollWithTimeout(url, { interval: 10000 });
  return response;
}

Testing Guidelines

Manual Testing Checklist

Before submitting a PR, test:

  • Setup completes without errors
  • DreamFactory UI accessible at http://localhost:8080
  • Demo database works
  • MCP integration connects (Claude Desktop or Code)
  • Can query demo database via Claude
  • Logs are clean (no errors in docker compose logs)

Platform Testing

  • macOS (Intel & Apple Silicon if possible)
  • Linux (Ubuntu/Debian preferred)
  • Windows (WSL2)

Edge Cases

  • Port conflict handling
  • Docker not installed error
  • Invalid admin password (< 16 chars)
  • Network timeout during build

Pull Request Process

  1. Update documentation if you changed behavior
  2. Add yourself to contributors (we'll do this automatically)
  3. Link to related issue (e.g., "Fixes #123")
  4. Describe your changes:
    • What problem does this solve?
    • How did you test it?
    • Any breaking changes?

PR Template:

## Description
Brief description of changes

## Motivation
Why is this change needed?

## Testing
How did you test this?
- [ ] Tested on macOS
- [ ] Tested on Linux
- [ ] Tested on Windows

## Screenshots (if applicable)

Roadmap Contributions

See ROADMAP.md for planned features.

Claiming a feature:

  1. Comment on the related GitHub issue: "I'd like to work on this"
  2. Wait for maintainer approval (avoid duplicate work)
  3. Follow development workflow above

Questions?

License

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

Thank you for contributing! 🎉