Developer Hub
Build features, contribute code, and customize YMCA Website Services.
Welcome, Developers! 💻
Tools, documentation, and resources for building with YMCA Website Services.
New here? Start with our Getting Started Guide for Developers.
Getting Started for Developers
Set up your development environment, understand contribution workflows, and submit your first pull request.
You'll learn:- Local development setup (DDEV)
- Git workflow and branching strategy
- Coding standards and best practices
- Submitting and reviewing pull requests
Tech Stack
Understand YMCA Website Services architecture: Drupal 11, Composer workflows, Docker environments, and development tools.
You'll learn:- Drupal 11 core and modules
- Composer dependency management
- Local development setup (DDEV)
- CI/CD pipeline
Quick Reference
Drush commands, Git workflows, debugging techniques, and developer shortcuts. Essential commands at your fingertips.
You'll learn:- Common Drush commands
- Configuration import/export
- Cache clearing and rebuilding
- Database updates
Troubleshooting
Debug WSOD, permission errors, Composer conflicts, and performance issues. Comprehensive error solutions.
You'll learn:- Debugging White Screen of Death
- Fixing Composer dependencies
- Resolving permission errors
- Performance optimization
Contributing
Submit pull requests, follow code standards, and join the YMCA Website Services community. Your contributions matter!
You'll learn:- Contribution workflow
- Code review standards
- Pull request guidelines
- Community communication
1 - 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
Install DDEV (Recommended) ⭐
Recommended: DDEV is the official local development tool for Drupal since June 2024. It provides a consistent, containerized environment that works across all platforms.
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
Pro Tip: Start with issues labeled
"good first issue" to get familiar with the contribution process.
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
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 MoreTheme Development
Customize YMCA themes or create your own with Twig templates.
View GuideTesting
Write unit tests, integration tests, and end-to-end tests.
Test GuideEssential 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:
- 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()
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:
- 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
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! 🚀