MokoCassiopeia/docs/QUICK_START.md

# Quick Start Guide - MokoCassiopeia Development

Get up and running with MokoCassiopeia development in minutes.

## Prerequisites

Before you begin, ensure you have:

- **Git** - For version control
- **PHP 8.0+** - Required runtime
- **Composer** - PHP dependency manager
- **Make** (optional) - For convenient commands
- **Code Editor** - VS Code recommended (tasks pre-configured)

## 5-Minute Setup

### 1. Clone the Repository

```bash
git clone https://github.com/mokoconsulting-tech/MokoCassiopeia.git
cd MokoCassiopeia
```

### 2. Install Development Dependencies

```bash
# Using Make (recommended)
make dev-setup

# Or manually
composer global require "squizlabs/php_codesniffer:^3.0"
composer global require phpstan/phpstan
composer global require "phpcompatibility/php-compatibility:^9.0"
composer global require codeception/codeception
```

### 3. Validate Everything Works

```bash
# Quick validation
make validate-required

# Or comprehensive validation
make validate
```

## Common Tasks

### Development Workflow

```bash
# 1. Make your changes
vim src/index.php

# 2. Validate locally
make validate-required

# 3. Check code quality
make quality

# 4. Commit
git add -A
git commit -m "feat: add new feature"
# (pre-commit hook runs automatically)

# 5. Push
git push origin your-branch
```

### Testing

```bash
# Run all tests
make test

# Run unit tests only
make test-unit

# Run acceptance tests only
make test-acceptance
```

### Code Quality

```bash
# Check everything
make quality

# PHP CodeSniffer only
make phpcs

# Auto-fix PHPCS issues
make phpcs-fix

# PHPStan only
make phpstan

# PHP compatibility check
make phpcompat
```

### Creating a Release Package

```bash
# Package with auto-detected version
make package

# Check package contents
ls -lh dist/
unzip -l dist/mokocassiopeia-*.zip
```

## VS Code Integration

If using VS Code, press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) and type "Run Task" to see available tasks:

- **Validate All** - Run all validation scripts (default test task)
- **Validate Required** - Run only required validations
- **PHP CodeSniffer** - Check code style
- **PHP CodeSniffer - Auto Fix** - Fix code style issues
- **PHPStan** - Static analysis
- **Run Tests** - Execute all tests
- **Create Package** - Build distribution ZIP
- **Install Git Hooks** - Set up pre-commit hooks

## Available Make Commands

Run `make help` to see all available commands:

```bash
make help              # Show all commands
make dev-setup         # Complete environment setup
make validate          # Run all validations
make test              # Run all tests
make quality           # Check code quality
make package           # Create distribution package
make clean             # Remove generated files
make check             # Quick check (validate + quality)
make all               # Complete build pipeline
```

## Project Structure

```
moko-cassiopeia/
├── src/                      # Joomla template source (template root)
│   ├── component.php         # Component template file
│   ├── index.php             # Main template file
│   ├── offline.php           # Offline page template
│   ├── error.php             # Error page template
│   ├── templateDetails.xml   # Template manifest
│   ├── html/                 # Module & component overrides
│   ├── media/                # Assets (CSS, JS, images, fonts)
│   ├── language/             # Frontend language files (en-GB, en-US)
│   └── administrator/        # Backend files
│       └── language/         # Backend language files
├── tests/                    # Test suites
├── docs/                     # Documentation
├── scripts/                  # Build scripts
├── .github/workflows/        # CI/CD workflows
├── Makefile                  # Make commands
└── README.md                 # Project overview
```

## Next Steps

### Learning the Workflow

1. **Read the Workflow Guide**: [docs/WORKFLOW_GUIDE.md](./WORKFLOW_GUIDE.md)
2. **Review Joomla Development**: [docs/JOOMLA_DEVELOPMENT.md](./JOOMLA_DEVELOPMENT.md)

### Creating Your First Feature

1. **Create a version branch** via GitHub Actions:
   - Go to Actions → Create version branch
   - Enter version (e.g., 03.06.00)
   - Select branch prefix: `dev/`
   - Run workflow

2. **Checkout the branch**:
   ```bash
   git fetch origin
   git checkout dev/03.06.00
   ```

3. **Make changes and test**:
   ```bash
   # Edit files
   vim src/index.php
   
   # Validate
   make validate-required
   
   # Check quality
   make quality
   ```

4. **Commit and push**:
   ```bash
   git add -A
   git commit -m "feat: your feature description"
   git push origin dev/03.06.00
   ```

5. **Watch CI**: Check GitHub Actions for automated testing

### Understanding the Release Process

```
Development → RC → Stable → Production
  (dev/)     (rc/)  (version/)  (main)
```

1. **dev/X.Y.Z** - Active development
2. **rc/X.Y.Z** - Release candidate testing
3. **version/X.Y.Z** - Stable release
4. **main** - Production (auto-merged from version/)

Use the Release Pipeline workflow to promote between stages.

## Troubleshooting

### Scripts Not Executable

```bash
make fix-permissions
### PHPStan/PHPCS Not Found

```bash
make install
# Or manually:
composer global require "squizlabs/php_codesniffer:^3.0" phpstan/phpstan
```

### CI Workflow Fails

1. Check the workflow logs in GitHub Actions
2. Run validation locally:
   ```bash
   make validate-required
   make quality
   ```

### Need Help?

- **Documentation**: Check [docs/](../docs/) directory
- **Issues**: Open an issue on GitHub
- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md)

## Best Practices

### Before Committing

```bash
# Always validate first
make validate-required

# Check quality for PHP changes
make quality

# Run tests if you changed functionality
make test
```

### Code Style

- Follow PSR-12 standards
- Use `make phpcs-fix` to auto-fix issues
- Add SPDX license headers to new files
- Keep functions small and focused

### Documentation

- Update docs when changing workflows
- Add comments for complex logic
- Update CHANGELOG.md with changes
- Keep README.md current

### Version Management

- Use semantic versioning: Major.Minor.Patch (03.06.00)
- Update CHANGELOG.md with all changes
- Follow the version hierarchy: dev → rc → version → main
- Never skip stages in the release process

## Useful Resources

- [Joomla Documentation](https://docs.joomla.org/)
- [PSR-12 Coding Standard](https://www.php-fig.org/psr/psr-12/)
- [Semantic Versioning](https://semver.org/)
- [Conventional Commits](https://www.conventionalcommits.org/)

## Quick Reference Card

```bash
# Setup
make dev-setup              # Initial setup

# Development
make validate-required      # Quick validation
make quality               # Code quality
make test                  # Run tests

# Building
make package               # Create ZIP

# Maintenance
make clean                 # Clean generated files
make fix-permissions       # Fix script permissions

# Help
make help                  # Show all commands
```

---

## Metadata

* Document: docs/QUICK_START.md
* Repository: [https://github.com/mokoconsulting-tech/MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia)
* Path: /docs/QUICK_START.md
* Owner: Moko Consulting
* Version: 03.06.03
* Status: Active
* Effective Date: 2026-01-30
* Classification: Public Open Source Documentation

## Revision History

| Date       | Change Summary                                        | Author          |
| ---------- | ----------------------------------------------------- | --------------- |
| 2026-01-30 | Updated metadata to MokoStandards format             | GitHub Copilot  |
| 2025-01-04 | Initial quick start guide created                    | GitHub Copilot  |