Getting Started for Developers

Set up your local environment, contribute code, and build custom features for YMCA Website Services.

Welcome! This guide will walk you through setting up a local development environment and making your first contribution to YMCA Website Services.

What You’ll Learn

By the end of this guide, you’ll be able to:

  • ✅ Set up a local development environment with DDEV
  • ✅ Clone and install YMCA Website Services locally
  • ✅ Understand the codebase structure and architecture
  • ✅ Create a custom module or theme modification
  • ✅ Submit your first pull request

Estimated time: 60-90 minutes


Step 1: Set Up Your Local Development Environment

Why DDEV?

  • Official Drupal recommendation
  • Cross-platform (Mac, Windows, Linux)
  • Pre-configured for Drupal
  • Includes database, web server, PHP, and tooling
  • Matches production environment

Installation Steps

macOS:

# Install using Homebrew
brew install ddev/ddev/ddev

# Start Docker Desktop (required)
# Download from https://www.docker.com/products/docker-desktop

Windows:

# Install using Chocolatey
choco install ddev

# Or download installer from:
# https://github.com/ddev/ddev/releases

Linux:

# Install script
curl -fsSL https://ddev.com/install.sh | bash

Verify Installation

# Check DDEV version
ddev version

# Expected output: ddev version v1.23.0 or higher

Step 2: Clone and Install YMCA Website Services

Choose Your Starting Point

For Contributing to Core:

# 1. Fork the repository on GitHub
# Visit: https://github.com/YCloudYUSA/yusaopeny

# 2. Clone YOUR fork
git clone git@github.com:YOUR_USERNAME/yusaopeny.git ymca-dev
cd ymca-dev

# 3. Add upstream remote
git remote add upstream git@github.com:YCloudYUSA/yusaopeny.git

# 4. Create a new branch
git checkout -b feature/my-contribution

For Custom Development:

# 1. Create a new project
composer create-project ycloudyusa/yusaopeny-project ymca-dev --no-interaction
cd ymca-dev

Install with DDEV

# 1. Configure DDEV
ddev config --project-type=drupal10 --docroot=web --create-docroot

# 2. Start DDEV
ddev start

# 3. Install Drupal
ddev drush site:install openy \
  --account-name=admin \
  --account-pass=admin \
  --site-name='YMCA Dev'

# 4. Get login link
ddev drush uli

🎉 Success! Your local YMCA Website Services site is running at the URL shown by ddev describe.

Essential DDEV Commands

# Start environment
ddev start

# Stop environment
ddev stop

# Run Drush commands
ddev drush cr

# Run Composer commands
ddev composer require drupal/module_name

# SSH into container
ddev ssh

# View site URL and credentials
ddev describe

# Import database
ddev import-db --file=dump.sql.gz

# Export database
ddev export-db --file=dump.sql.gz

Step 3: Understand the Codebase

Project Structure

yusaopeny/
├── web/                          # Drupal root
   ├── modules/
      ├── contrib/             # Downloaded modules
      └── custom/              # Your custom modules
   ├── themes/
      ├── contrib/             # Downloaded themes
      └── custom/              # Your custom themes
   ├── profiles/
      └── openy/               # YMCA installation profile
   └── sites/default/           # Site-specific files
├── config/                       # Configuration management
   └── sync/                    # Exported configuration
├── vendor/                       # Composer dependencies
├── composer.json                 # Project dependencies
└── .ddev/                       # DDEV configuration

Key Directories

DirectoryPurpose
web/modules/custom/Custom modules for YMCA features
web/themes/custom/Custom themes (Carnation)
config/sync/Configuration files (version controlled)
web/profiles/openy/Installation profile and defaults

YMCA-Specific Modules

Familiarize yourself with these core YMCA modules:

  • openy_activity_finder - Program search integration (Daxko, ActiveNet, Personify)
  • openy_schedules - Class schedule displays
  • openy_loc_branch - Branch/location functionality
  • openy_node_ - Content type modules (landing_page, event, etc.)
  • openy_prgf_ - Paragraphs components (legacy)
  • lb_ - Layout Builder components (modern)

Step 4: Create Your First Contribution

Find a Good First Issue

Read the Contribution Guidelines ⭐

Before contributing, review:

→ Contribution Guidelines - Required reading

Key points:

  • Code of Conduct expectations
  • Branching strategy (feature branches from main)
  • Commit message conventions
  • Pull request process
  • Code review expectations

Create a Custom Module Example

Let’s create a simple “Hello YMCA” module to understand the structure:

# 1. Create module directory
mkdir -p web/modules/custom/hello_ymca

# 2. Create .info.yml file
cat > web/modules/custom/hello_ymca/hello_ymca.info.yml << 'EOF'
name: Hello YMCA
type: module
description: 'A simple example module for YMCA Website Services'
package: YMCA Custom
core_version_requirement: ^10 || ^11
dependencies:
  - drupal:node
EOF

# 3. Create a simple controller
mkdir -p web/modules/custom/hello_ymca/src/Controller

Controller file (web/modules/custom/hello_ymca/src/Controller/HelloController.php):

<?php

namespace Drupal\hello_ymca\Controller;

use Drupal\Core\Controller\ControllerBase;

/**
 * Returns responses for Hello YMCA routes.
 */
class HelloController extends ControllerBase {

  /**
   * Builds the response.
   */
  public function content() {
    $build['content'] = [
      '#type' => 'markup',
      '#markup' => $this->t('Hello from YMCA Website Services!'),
    ];
    return $build;
  }

}

Routing file (web/modules/custom/hello_ymca/hello_ymca.routing.yml):

hello_ymca.hello:
  path: '/hello-ymca'
  defaults:
    _controller: '\Drupal\hello_ymca\Controller\HelloController::content'
    _title: 'Hello YMCA'
  requirements:
    _permission: 'access content'

Enable and test:

# Enable module
ddev drush en hello_ymca -y

# Clear cache
ddev drush cr

# Visit /hello-ymca in your browser

Step 5: Submit Your First Pull Request

Git Workflow (Feature Branch)

# 1. Create feature branch from main
git checkout main
git pull upstream main
git checkout -b feature/issue-123-fix-description

# 2. Make your changes
# Edit files...

# 3. Stage and commit
git add .
git commit -m "Fix: Description of what you fixed (#123)

- Detailed explanation of changes
- Why the change was needed
- Any related issues

Fixes #123"

# 4. Push to YOUR fork
git push origin feature/issue-123-fix-description

Commit Message Best Practices

Format:

Type: Short description (#issue-number)

- Detailed bullet points
- Explaining the change
- And the reasoning

Fixes #123

Types:

  • Fix: - Bug fixes
  • Feature: - New features
  • Refactor: - Code improvements
  • Docs: - Documentation updates
  • Test: - Test additions/fixes
  • Chore: - Build/tooling updates

Create Pull Request

  1. Go to GitHub - Your fork’s repository
  2. Click “Compare & pull request”
  3. Fill in the template:
    • Title: Clear, concise description
    • Description: What, why, how
    • Screenshots: If UI changes
    • Testing steps: How reviewers can test
    • Checklist: Complete all items
  4. Request reviews - Tag 2 reviewers (optimal per research)
  5. Link issue - Use “Fixes #123” in description

Pull Request Checklist

  • Code follows Drupal coding standards

  • Added/updated tests if applicable

  • Updated documentation

  • No merge conflicts

  • Passes automated tests

  • Screenshots for UI changes

  • Tested on multiple browsers/devices


Next Steps

Now that you’ve set up your environment and made your first contribution, explore these advanced topics:

Continue Learning

Module Development

Deep dive into custom module development, services, and dependency injection.

Learn More
Theme Development

Customize YMCA themes or create your own with Twig templates.

View Guide
Testing

Write unit tests, integration tests, and end-to-end tests.

Test Guide

Essential Developer Resources

Advanced Topics


Quick Reference

Common Git Commands

# Update your fork's main branch
git checkout main
git pull upstream main
git push origin main

# Create feature branch
git checkout -b feature/issue-123-description

# View status
git status

# View diff
git diff

# Stage changes
git add file.php

# Commit
git commit -m "Fix: Description (#123)"

# Push to your fork
git push origin feature/issue-123-description

# Rebase on latest main
git checkout feature/issue-123-description
git rebase main

# Squash commits (interactive)
git rebase -i HEAD~3

Common Drush Commands

# Clear cache
ddev drush cr

# Enable module
ddev drush en module_name -y

# Uninstall module
ddev drush pmu module_name -y

# Export configuration
ddev drush config:export -y

# Import configuration
ddev drush config:import -y

# Update database
ddev drush updb -y

# Generate login link
ddev drush uli

# Watch logs
ddev drush watchdog:tail

# Run cron
ddev drush cron

Common Composer Commands

# Require new module
ddev composer require drupal/module_name

# Remove module
ddev composer remove drupal/module_name

# Update all packages
ddev composer update

# Update specific package
ddev composer update drupal/core --with-all-dependencies

# Show outdated packages
ddev composer outdated

# Validate composer.json
ddev composer validate

IDE Setup (PhpStorm)

Recommended plugins:

  • Drupal Symfony Bridge
  • PHP Annotations
  • Twig
  • Composer.json support

Code style:

  1. Settings → PHP → Code Sniffer
  2. Configuration: /path/to/vendor/bin/phpcs
  3. Coding standard: Drupal

Drupal settings:

  1. Settings → PHP → Drupal
  2. Enable Drupal integration
  3. Set Drupal installation path: web/

Code Quality and Standards

Drupal Coding Standards

All contributions must follow Drupal coding standards:

# Install PHP_CodeSniffer
ddev composer require --dev drupal/coder
ddev composer require --dev dealerdirect/phpcodesniffer-composer-installer

# Check your code
ddev exec phpcs --standard=Drupal web/modules/custom/your_module/

# Auto-fix issues
ddev exec phpcbf --standard=Drupal web/modules/custom/your_module/

Modern Drupal Best Practices

✅ DO:

  • Use dependency injection for services
  • Use Events and Subscribers (not hooks when possible)
  • Type-hint function parameters
  • Document with PHPDoc blocks
  • Use configuration entities for exportable config
  • Write tests for new functionality

❌ DON’T:

  • Use drupal_set_message() (use Messenger service)
  • Use db_query() (use Database API)
  • Use l() or url() (use Url and Link classes)
  • Store data in variables (use State API or Config)
  • Use global $user (inject current_user service)

Security Best Practices

  • ✅ Always sanitize user input
  • ✅ Use checkPlain(), Xss::filter(), or render arrays
  • ✅ Check permissions before granting access
  • ✅ Use CSRF tokens for state-changing operations
  • ✅ Validate and sanitize database queries
  • ✅ Follow OWASP top 10 guidelines

Need Help?

Troubleshooting

  • DDEV not starting? Check Docker is running (docker ps)
  • Composer memory errors? Increase PHP memory: ddev config --php-memory-limit=4G
  • Git conflicts? Rebase on latest main and resolve conflicts
  • Code style issues? Run phpcs and phpcbf to auto-fix

Get Support

Code Review Process

What to expect:

  1. Automated checks - Tests run automatically (5-10 minutes)
  2. Peer review - 2 reviewers will check your code (2-4 days typical)
  3. Feedback - You may be asked to make changes
  4. Approval - Once approved by 2+ reviewers
  5. Merge - Maintainer merges to main branch

How to get faster reviews:

  • Keep PRs small and focused (< 400 lines ideal)
  • Write clear commit messages
  • Add tests for new functionality
  • Respond promptly to feedback
  • Test thoroughly before submitting

Best Practices

Git Workflow

  • ✅ Always branch from latest main
  • ✅ One feature/fix per branch
  • ✅ Keep commits focused and atomic
  • ✅ Write descriptive commit messages
  • ✅ Rebase on main before submitting PR
  • ✅ Keep PRs small (easier to review)

Development Workflow

  • ✅ Use DDEV for consistent environment
  • ✅ Export configuration after changes (drush cex)
  • ✅ Never commit sites/default/files/
  • ✅ Test on multiple browsers
  • ✅ Check accessibility with screen readers
  • ✅ Test with real content

Code Organization

  • ✅ Keep modules small and focused
  • ✅ Use services for reusable logic
  • ✅ Leverage existing Drupal APIs
  • ✅ Follow Drupal file structure conventions
  • ✅ Document complex logic with comments
  • ✅ Write self-documenting code (clear naming)

Testing

  • ✅ Write tests for new features
  • ✅ Run tests locally before pushing
  • ✅ Test edge cases and error conditions
  • ✅ Test with JavaScript disabled
  • ✅ Test responsive layouts
  • ✅ Test with different user roles

Community Guidelines

Code of Conduct

YMCA Website Services follows the Drupal Code of Conduct. All contributors must:

  • ✅ Be respectful and inclusive
  • ✅ Welcome newcomers
  • ✅ Assume good faith
  • ✅ Give constructive feedback
  • ✅ Focus on what’s best for the community

Getting Involved

Ways to contribute:

  • 🐛 Report bugs
  • 💡 Suggest features
  • 📝 Improve documentation
  • 🔍 Review pull requests
  • 💬 Help others in Slack
  • 🎓 Share knowledge in blog posts
  • 🎤 Present at community calls

Ready to code? Join us on Slack, grab a good first issue, and start contributing! 🚀