Getting Started for Developers
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
Install DDEV (Recommended) ⭐
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
Directory | Purpose |
---|---|
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 fixesFeature:
- New featuresRefactor:
- Code improvementsDocs:
- Documentation updatesTest:
- Test additions/fixesChore:
- Build/tooling updates
Create Pull Request
- Go to GitHub - Your fork’s repository
- Click “Compare & pull request”
- 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
- Request reviews - Tag 2 reviewers (optimal per research)
- 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 MoreEssential Developer Resources
- Drupal API Documentation - Complete API reference
- Drupal Coding Standards - Required reading
- YMCA GitHub Repository - Source code and issues
- Configuration Management - Import/export config
- Layout Builder API - Custom block development
Advanced Topics
- Custom Block Plugins - Create Layout Builder blocks
- Activity Finder Integration - Connect to external systems
- Deployment Workflows - CI/CD and automation
- Performance Optimization - Caching, queries, and profiling
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:
- Settings → PHP → Code Sniffer
- Configuration:
/path/to/vendor/bin/phpcs
- Coding standard: Drupal
Drupal settings:
- Settings → PHP → Drupal
- Enable Drupal integration
- 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()
orurl()
(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
andphpcbf
to auto-fix
Get Support
- YMCA Slack - Real-time developer chat (#development channel)
- GitHub Issues - Report bugs or request features
- GitHub Discussions - Ask questions
- Monthly Community Calls - Live Q&A sessions
- Drupal.org Documentation - Official Drupal docs
Code Review Process
What to expect:
- Automated checks - Tests run automatically (5-10 minutes)
- Peer review - 2 reviewers will check your code (2-4 days typical)
- Feedback - You may be asked to make changes
- Approval - Once approved by 2+ reviewers
- 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! 🚀