Thank you for your interest in contributing to the Open Source Project Generator! We welcome contributions from everyone and are grateful for every pull request, bug report, and feature suggestion.
- Code of Conduct
- Getting Started
- Development Setup
- Contributing Guidelines
- Pull Request Process
- Coding Standards
- Testing Guidelines
- Documentation
- Issue Reporting
- Security Issues
- Community
This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.
- 🐛 Bug Reports: Help us identify and fix bugs
- ✨ Feature Requests: Suggest new features or improvements
- 📝 Documentation: Improve our documentation
- 🧪 Testing: Add or improve tests
- 💻 Code: Submit bug fixes or new features
- 🔧 Tools: Add support for new bootstrap tools
- Check existing issues: Look for existing issues or discussions about your idea
- Create an issue: For significant changes, create an issue first to discuss the approach
- Fork the repository: Create your own fork to work on
- Read the guidelines: Familiarize yourself with our coding standards and processes
Ensure you have the required tools installed:
- Go: 1.25.0 or later
- Make: Build automation tool
- Git: Latest stable version
- Docker: Latest stable version (optional, for testing)
-
Fork and Clone
# Fork the repository on GitHub, then clone your fork git clone https://github.com/YOUR_USERNAME/open-source-project-generator.git cd open-source-project-generator # Add upstream remote git remote add upstream https://github.com/cuesoftinc/open-source-project-generator.git
-
Environment Setup
# Install dependencies go mod download # Build the generator make build
-
Verify Installation
# Run tests to verify setup make test # Run the generator ./bin/generator --help
# Keep your fork updated
git fetch upstream
git checkout main
git merge upstream/main
# Create a feature branch
git checkout -b feature/your-feature-name
# Make your changes
# ... edit files ...
# Run all checks (recommended before committing)
make check
# This runs: fmt, vet, lint, test
# Or run individual checks
make test # Run tests
make lint # Run linter
make security-scan # Run security scans
# Commit your changes
git add .
git commit -m "feat: add your feature description"
# Push to your fork
git push origin feature/your-feature-name
# Create a Pull Request on GitHubUse Docker Compose for a containerized development environment:
# Start development environment
docker compose --profile development up -d generator-dev
# Enter interactive shell
docker compose --profile development run --rm generator-dev bash
# Inside the container, you can:
make build
make test
make check
# Run tests in containers
docker compose --profile testing up generator-test
# Run security scans in containers
docker compose --profile security up generator-security
# Run linting in containers
docker compose --profile lint up generator-lint
# Stop all services
docker compose downSee docker-compose.yml for all available profiles and services.
- Fix existing functionality that doesn't work as expected
- Include tests that verify the fix
- Update documentation if necessary
- Add new functionality to the generator
- Discuss significant features in an issue first
- Include comprehensive tests
- Update documentation and examples
- Improve existing documentation
- Add missing documentation
- Fix typos and grammar
- Add examples and tutorials
- Add support for new CLI tools (Vite, Angular, etc.)
- Improve existing tool executors
- Add fallback generators for tools
- Update tool version requirements
- Add missing test coverage
- Improve existing tests
- Add integration or end-to-end tests
- Performance and load testing
- Issue First: For significant changes, create an issue to discuss the approach
- Small PRs: Keep pull requests focused and small when possible
- Clear Description: Provide clear descriptions of what your PR does
- Tests Required: All code changes must include appropriate tests
- Documentation: Update documentation for any user-facing changes
- All Checks Pass: Run all checks (
make check) - Tests Pass: Ensure all tests pass locally (
make test) - Security Scans: Run security scans if needed (
make security-scan) - Documentation: Update relevant documentation
- Tool Testing: Test tool executors if bootstrap code was modified
- Rebase: Rebase your branch on the latest main branch
- Docker: Test Docker builds if Dockerfiles were modified (
make docker-build)
## Pull Request Checklist
- [ ] I have read the [Contributing Guidelines](CONTRIBUTING.md)
- [ ] My code follows the project's coding standards
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] All new and existing tests pass
- [ ] I have updated the documentation accordingly
- [ ] My commits are properly formatted and descriptive
- [ ] I have rebased my branch on the latest main branch
- [ ] I have tested tool executors if bootstrap code was modified
## Description
Brief description of changes...
## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Bootstrap tool update
- [ ] Performance improvement
- [ ] Code refactoring
## Testing
Describe the tests you ran and how to reproduce them...
## Tool Executor Testing (if applicable)
If you modified tool executors, describe how you tested them:
- [ ] Generated sample projects with modified executors
- [ ] Verified generated projects build successfully
- [ ] Tested with different component combinations
- [ ] Tested fallback generation when tool is unavailable- Automated Checks: All PRs must pass automated CI checks
- Code Review: At least one maintainer must review and approve
- Tool Testing: Tool executor changes are tested with sample generation
- Merge: Approved PRs are merged by maintainers
- Consistency: Follow existing code patterns and conventions
- Readability: Write code that is easy to read and understand
- Simplicity: Prefer simple solutions over complex ones
- Performance: Consider performance implications of your changes
- Security: Follow security best practices
// Use clear, descriptive names
type BootstrapExecutor struct {
logger *logger.Logger
}
// Document public functions
// Execute runs the bootstrap tool with the provided configuration
func (e *TemplateEngine) ProcessTemplate(templatePath string, config *models.ProjectConfig) error {
if err := e.validateTemplate(templatePath); err != nil {
return fmt.Errorf("template validation failed: %w", err)
}
// Process template logic here
return nil
}- Packages: lowercase (
template,validation) - Types: PascalCase (
TemplateEngine,ProjectConfig) - Functions: PascalCase for public (
ProcessTemplate), camelCase for private (validateTemplate) - Variables: camelCase (
templatePath,configManager) - Constants: PascalCase (
DefaultTimeout,MaxRetries)
The project follows a tool-orchestration architecture with clear separation of concerns:
cmd/ # Command-line applications
└── generator/ # Main generator CLI
└── main.go # Main entry point with Cobra commands
internal/ # Private application code
├── config/ # Configuration parsing and validation
│ ├── parser.go # YAML/JSON parsing
│ ├── validator.go # Configuration validation
│ ├── schema.go # Configuration schema
│ ├── nextjs_validator.go # Next.js validation
│ ├── go_validator.go # Go validation
│ ├── android_validator.go # Android validation
│ └── ios_validator.go # iOS validation
├── generator/ # Component generators
│ ├── bootstrap/ # Bootstrap tool executors
│ │ ├── executor.go # Base executor
│ │ ├── nextjs.go # Next.js executor (uses create-next-app)
│ │ ├── golang.go # Go executor (uses go mod init)
│ │ ├── android.go # Android executor (uses Gradle)
│ │ └── ios.go # iOS executor (uses Xcode)
│ ├── fallback/ # Fallback generators
│ │ ├── generator.go # Generator interface and registry
│ │ ├── android.go # Android fallback
│ │ ├── ios.go # iOS fallback
│ │ └── templates/ # Minimal templates
│ └── mapper/ # Structure mapping
│ └── structure.go # Maps generated output to standard layout
└── orchestrator/ # Project generation orchestration
├── coordinator.go # Main coordinator
├── tool_discovery.go # Tool detection and version checking
├── executor_registry.go # Executor registry
├── integration.go # Component integration
├── rollback.go # Rollback on failure
├── progress.go # Progress tracking
└── cache/ # Tool metadata caching
└── manager.go # Cache management
pkg/ # Public interfaces and libraries
├── cli/ # CLI utilities and error types
│ ├── exit_codes.go # Exit code definitions
│ ├── diagnostics.go # Error diagnostics
│ ├── suggestion_engine.go # Error suggestions
│ └── interactive/ # Interactive prompts
│ └── prompter.go # User prompts
├── filesystem/ # File system operations
│ ├── operations.go # File operations
│ └── backup.go # Backup and restore
├── interfaces/ # Core interfaces
│ ├── executor.go # Executor interface
│ ├── generator.go # Generator interface
│ └── mapper.go # Mapper interface
├── logger/ # Logging infrastructure
│ ├── logger.go # Logger implementation
│ └── formatter.go # Output formatting
├── models/ # Data structures
│ ├── project.go # Project configuration
│ ├── result.go # Generation results
│ └── tool.go # Tool metadata
├── security/ # Security operations
│ ├── sanitizer.go # Path sanitization
│ ├── scanner.go # Security scanning
│ ├── validator.go # Input validation
│ └── tool_validator.go # Tool command validation
└── testhelpers/ # Test utilities
└── environment.go # Test environment setup
├── utils/ # Utility functions
└── constants/ # Application constants
- Use Go text/template syntax
- Include proper variable substitution
- Add conditional rendering for components
- Follow consistent naming patterns
- All templates must be syntactically valid
- Generated projects must build successfully
- Include proper error handling
- Use secure defaults
For detailed guidelines on maintaining template files, see:
- Template Development Guide - Comprehensive guide for template development
- API Reference - Template functions and variables reference
- Configuration Guide - Template configuration options
Key requirements for template changes:
- All used functions must have corresponding import statements
- Follow Go import organization conventions (standard library, third-party, local)
- Run validation tools before committing:
go run cmd/generator/main.go template validate - Test template compilation with sample data:
go run cmd/generator/main.go generate --config configs/minimal.yaml --output test-validation
- Code Comments: Explain why, not what
- Function Documentation: Document all public functions
- README Updates: Update README for user-facing changes
- Template Documentation: Document template variables and usage
- Security Documentation: Update SECURITY.md for security-related changes
- Distribution Documentation: Update DISTRIBUTION.md for build/release changes
- Docker Documentation: Update docker-compose.yml comments for service changes
Use Conventional Commits format:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Types:
feat: New featurefix: Bug fixdocs: Documentation changesstyle: Code style changes (formatting, etc.)refactor: Code refactoringtest: Adding or updating testschore: Maintenance taskstemplate: Template changes
Examples:
feat(cli): add interactive component selection
fix(template): handle null values in package.json generation
docs(readme): update installation instructions
template(frontend): update Next.js to version 15
test(validation): add integration tests for project validation
- Unit Tests: All new functions must have unit tests
- Integration Tests: Add integration tests for new features
- Template Tests: Test template generation and validation
- Coverage: Maintain or improve test coverage
func TestTemplateEngine_ProcessTemplate(t *testing.T) {
// Setup
engine := template.NewEngine()
config := &models.ProjectConfig{
Name: "test-project",
Organization: "test-org",
}
// Execute
result, err := executor.Execute(ctx, spec)
// Assert
assert.NoError(t, err)
}func TestProjectGeneration_FullWorkflow(t *testing.T) {
// Test complete project generation workflow
tempDir := t.TempDir()
config := &models.ProjectConfig{
Name: "integration-test",
OutputPath: tempDir,
Components: models.Components{
Frontend: models.FrontendComponents{MainApp: true},
Backend: models.BackendComponents{API: true},
},
}
// Generate project
err := generateProject(config)
assert.NoError(t, err)
// Verify generated files exist
assert.FileExists(t, filepath.Join(tempDir, "integration-test", "README.md"))
assert.FileExists(t, filepath.Join(tempDir, "integration-test", "Makefile"))
}# Run all tests with coverage
make test
# Run tests with specific flags
make test TEST_FLAGS="-v -race"
# Run tests with integration tags
make test TEST_FLAGS="-tags=integration"
go test ./internal/generator/...
# Run all security scans (gosec, govulncheck, staticcheck)
make security-scan
# Run linting
make lint
# Format code
make fmt
# Run go vet
make vet
# Using Docker Compose for testing
docker compose --profile testing up generator-test
docker compose --profile testing up generator-test-coverage
docker compose --profile testing up generator-test-integration
# Validate templates (recommended before committing template changes)
./bin/generator template validate
# Generate test project to verify templates
./bin/generator generate --config configs/minimal.yaml --output test-validation- Code Documentation: Inline comments and function documentation
- CLI Documentation: Command help text and usage examples
- User Documentation: README, guides, and tutorials
- Template Documentation: Template usage and variable reference
- Developer Documentation: Architecture decisions, setup guides
- Clear and Concise: Write clear, easy-to-understand documentation
- Examples: Include practical examples and code snippets
- Up-to-Date: Keep documentation synchronized with code changes
- Accessible: Use inclusive language and consider accessibility
When reporting bugs, please include:
- Clear Title: Descriptive title summarizing the issue
- Environment: OS, Go version, generator version
- Steps to Reproduce: Detailed steps to reproduce the issue
- Expected Behavior: What you expected to happen
- Actual Behavior: What actually happened
- Configuration: Project configuration used (if applicable)
- Logs: Relevant error messages or logs
When requesting features, please include:
- Problem Statement: What problem does this solve?
- Proposed Solution: How should this feature work?
- Alternatives: What alternatives have you considered?
- Use Cases: Specific use cases for this feature
- Templates: Which templates would be affected?
Do not report security vulnerabilities through public GitHub issues.
Instead, please report them responsibly:
- Security Advisory: Use GitHub's private vulnerability reporting
- Details: See SECURITY.md for complete security policy and reporting guidelines
When contributing code, follow these security practices:
- Path Sanitization: Always use
pkg/security/SanitizePath()for user-provided paths - Categorized Errors: Use error types from
pkg/clipackage - No Code Execution: Never execute user-provided code
- Input Validation: Validate all user inputs through
internal/config/validators - Tool Execution: Validate all tool commands before execution
- File Permissions: Use restrictive permissions (0600 for files, 0750 for directories)
- Security Scanning: Run
make security-scanbefore submitting PRs
See SECURITY.md for detailed security guidelines.
- GitHub Discussions: For general questions and discussions
- GitHub Issues: For bug reports and feature requests
- Email: For private communications
- Be Respectful: Treat everyone with respect and kindness
- Be Inclusive: Welcome people of all backgrounds and experience levels
- Be Constructive: Provide helpful feedback and suggestions
- Be Patient: Remember that everyone is learning and growing
The codebase has been refactored into a modular architecture. Understanding this structure is crucial for effective contributions.
- Identify the Package: Determine which package the feature belongs to based on the modular structure
- Check Interfaces: Ensure the feature fits existing interfaces in
pkg/interfaces/or create new ones - Follow Patterns: Use existing patterns for similar functionality within the same package
- Maintain Modularity: Keep components focused and avoid cross-cutting concerns
- Add Tests: Include comprehensive tests for new components
- Update Documentation: Document new functionality and interfaces
- Locate Components: Use the modular package structure to find relevant code quickly
- Check Dependencies: Understand component dependencies through interfaces in
pkg/interfaces/ - Respect Boundaries: Ensure changes don't violate component boundaries
- Test Changes: Ensure changes don't break existing functionality
- Update Tests: Modify tests to reflect changes, including component-specific tests
- Validate Integration: Run integration tests to ensure system coherence
CLI Development (cmd/generator/ and pkg/cli/):
- Main Entry: Main CLI logic in
cmd/generator/main.go - Error Types: Custom error types in
pkg/cli/exit_codes.go - Diagnostics: Error diagnostics in
pkg/cli/diagnostics.go - Suggestions: Error suggestions in
pkg/cli/suggestion_engine.go - Interactive: Interactive prompts in
pkg/cli/interactive/
Bootstrap Tool Development (internal/generator/bootstrap/):
- Executors: Tool executors in
internal/generator/bootstrap/(~200 lines max per executor) - Base Executor: Common functionality in
executor.go - Tool-Specific: Component executors (nextjs.go, golang.go, android.go, ios.go)
- Testing: Comprehensive tests for each executor
Fallback Generator Development (internal/generator/fallback/):
- Generators: Fallback generators for when tools are unavailable
- Android: Android fallback in
android.go - iOS: iOS fallback in
ios.go - Templates: Minimal templates in
templates/directory
Configuration Development (internal/config/):
- Parser: Configuration parsing in
parser.go - Validator: Configuration validation in
validator.go - Component Validators: Component-specific validation (nextjs_validator.go, go_validator.go, etc.)
- Schema: Configuration schema in
schema.go
- Keep Files Small: Target maximum 1,000 lines per file (strictly enforced)
- Single Responsibility: Each file should have one clear, focused purpose
- Interface First: Design interfaces in
pkg/interfaces/before implementations - Component Isolation: Ensure components can be tested and developed independently
- Clear Dependencies: Use dependency injection through interfaces
- Test Coverage: Maintain high test coverage for all components
- Documentation: Keep documentation up-to-date with changes
- Package Cohesion: Keep related functionality within the same package
- Minimal Coupling: Minimize dependencies between packages
For detailed information about the package structure, see the Package Structure Documentation and Migration Guide.
- README.md: Project overview and quick start
- SECURITY.md: Security practices and reporting
- DISTRIBUTION.md: Distribution and release process
- env.example: Environment variable reference
- docker-compose.yml: Docker orchestration with profiles
- Go Documentation: https://golang.org/doc/
- Cobra CLI: https://cobra.dev/
- Go Templates: https://pkg.go.dev/text/template
- Testing: https://golang.org/doc/tutorial/add-a-test
- Docker Compose: https://docs.docker.com/compose/
- Conventional Commits: https://www.conventionalcommits.org/
Understanding the project structure helps with contributions:
Core Directories:
.
├── cmd/ # Command-line applications
│ └── generator/ # Main generator CLI (main.go)
├── internal/ # Private application code
│ ├── config/ # Configuration parsing and validation
│ ├── generator/ # Component generators
│ │ ├── bootstrap/ # Bootstrap tool executors (nextjs, go, android, ios)
│ │ ├── fallback/ # Fallback generators when tools unavailable
│ │ └── mapper/ # Structure mapping
│ └── orchestrator/ # Project generation orchestration
│ └── cache/ # Tool metadata caching
├── pkg/ # Public interfaces and libraries
│ ├── cli/ # CLI utilities and error types
│ │ └── interactive/ # Interactive prompts
│ ├── filesystem/ # File operations
│ ├── interfaces/ # Core interfaces
│ ├── logger/ # Logging infrastructure
│ ├── models/ # Data structures
│ ├── security/ # Security operations
│ └── testhelpers/ # Test utilities
├── configs/ # Example configuration files
├── docs/ # Documentation
├── scripts/ # Build and utility scripts
└── .github/ # GitHub workflows and templates
docs/: Documentation filesoutput/: Generated project output
Docker Files:
Dockerfile: Production image (alpine:3.22, ~39 MB, UID 1001)Dockerfile.dev: Development image (golang:1.25-alpine, ~500 MB, UID 1001)Dockerfile.build: Build image (ubuntu:25.10, ~1.5 GB, UID 1001)docker-compose.yml: Multi-profile orchestration (production, development, testing, build, lint, security)
Configuration Files:
Makefile: Build automation and commandsgo.mod: Go dependencies (Go 1.25.0)env.example: Environment variable reference
Documentation:
README.md: Project overview and quick startCONTRIBUTING.md: This file - contribution guidelinesSECURITY.md: Security practices and reportingDISTRIBUTION.md: Distribution and release processLICENSE: MIT License
Important Notes:
- All Docker containers use UID 1001 for consistency
- Use
pkg/security/for path sanitization - Use
pkg/clierror types for categorized error handling - Follow the modular architecture patterns
Q: How do I add support for a new tool?
A: Create a new executor in internal/generator/bootstrap/, register it in the tool discovery system, and add tests. See docs/ADDING_TOOLS.md for detailed instructions.
Q: How do I test tool executor changes?
A: Run make test for unit tests, then test template generation manually with ./bin/generator generate or use Docker Compose: docker compose --profile testing up generator-test.
Q: What should I work on as a first contribution?
A: Look for issues labeled good first issue or help wanted. Template improvements, documentation updates, and test additions are often good starting points.
Q: How do I update package versions in templates?
A: Update the version variables in template files and test that generated projects build successfully with the new versions. Run make test and generate a test project to verify.
Q: Can I add support for a new technology stack? A: Yes! Create an issue first to discuss the approach, then add the necessary templates and update the CLI to support the new stack.
Q: How do I work with Docker for development?
A: Use docker compose --profile development run --rm generator-dev bash to get an interactive shell with all development tools. All containers use UID 1001.
Q: What security practices should I follow?
A: Always use pkg/security/SanitizePath() for user paths, return categorized errors from pkg/cli error types, and run make security-scan before submitting PRs. See SECURITY.md for details.
Q: How do I run CI checks locally?
A: Run make check for quick checks (fmt, vet, lint, test) or make ci for the full CI pipeline. For release validation, run make release.
Q: What's the difference between the three Dockerfiles?
A: Dockerfile is for production (39 MB), Dockerfile.dev is for development with all tools (500 MB), and Dockerfile.build is for creating packages (1.5 GB). All use UID 1001.
Thank you for contributing to the Open Source Project Generator! Your contributions help developers worldwide create better projects with modern best practices.
# Development
make build # Build for current platform
make test # Run tests with coverage
make check # Run all checks (fmt, vet, lint, test)
make fmt # Format code
make dev # Run in development mode
# Quality Assurance
make lint # Run linter (auto-installs if needed)
make security-scan # Run all security scans (auto-installs tools)
make ci # Run full CI pipeline
make release # Full release validation
# Docker Compose
docker compose --profile development run --rm generator-dev bash
docker compose --profile testing up generator-test
docker compose --profile lint up generator-lint
docker compose --profile security up generator-security
# Testing
make test # Tests with coverage
make test TEST_FLAGS="-v -race" # With race detector
make test TEST_FLAGS="-tags=integration" # Integration tests
# Building
make dist # Build cross-platform binaries
make package # Build distribution packages (DEB, RPM, Arch)
make release # Full release (test, lint, security-scan, dist, package)
make docker-build # Build production Docker image
make docker-test # Test Docker image
# Utilities
make version # Show version information
make validate-setup # Validate project setup
make clean # Clean all build artifacts (binaries, packages, reports, archives)Questions? Feel free to reach out through GitHub Discussions or create an issue.
Need Help? Check out our README, SECURITY.md, or DISTRIBUTION.md for more information.