zhongwei/gh-netresearch-claude-code-marketplace-skills-typo3-core-contributions

Files

Zhongwei Li e1d41c1e9f Initial commit

2025-11-30 08:43:24 +08:00

34 KiB

Raw Permalink Blame History

name, version, description, license

name	version	description	license
typo3-core-contributions	1.4.0	Guide contributors through the complete TYPO3 Core contribution workflow from account setup to patch submission for both code and documentation contributions. Trigger when: working with TYPO3 Forge issues (forge.typo3.org/issues/), preparing patches for TYPO3 Core, contributing to TYPO3 (code or documentation), submitting patches to Gerrit (review.typo3.org) or GitHub PRs (TYPO3-Documentation/), fixing TYPO3 bugs, managing WIP state, or debugging CI failures. Covers: Account setup, environment configuration with DDEV, commit message formatting, Gerrit review workflow, GitHub PR workflow for documentation, WIP state management (command-line and web UI), CI/CD debugging (CGL, PHPStan, unit tests), troubleshooting (60+ scenarios), code quality enforcement, and systematic patch submission for both code and documentation repositories.	Complete terms in LICENSE

TYPO3 Core Contributions

When to Use This Skill

Activate when the user:

Provides a TYPO3 Forge issue URL (e.g., https://forge.typo3.org/issues/105737)
Mentions contributing to TYPO3 Core, submitting patches, or fixing TYPO3 bugs
Needs help with Gerrit review workflow, rebasing, or patch updates
Wants to create a new Forge issue for a bug or feature
Requests TYPO3 development environment setup
Asks about TYPO3 commit message format or contribution guidelines

Scope: TYPO3 Core Contributions (Code AND Documentation)

This skill covers: All TYPO3 Core contributions

Core Code: PHP, JavaScript, CSS, tests via Gerrit (review.typo3.org)
Core Documentation: TYPO3CMS-Guide-* repositories via GitHub Pull Requests
Forge issue tracking (for both code and documentation)
Commit message standards
Contribution workflow guidance

Repository-Specific Workflows:

Core Code (typo3/typo3)

Submission: Gerrit (review.typo3.org)
Validation: Git commit-msg hooks
CI/CD: GitLab pipelines
Format: PHP, JavaScript, CSS, YAML
This skill handles: Complete workflow

Core Documentation (TYPO3-Documentation/*)

Submission: GitHub Pull Requests
Validation: GitHub Actions / pre-commit hooks
CI/CD: GitHub Actions
Format: reStructuredText (.rst files)
This skill handles: GitHub PR workflow, commit standards

Integration with typo3-docs-skill:

typo3-docs-skill: Validates and writes TYPO3 documentation format (reStructuredText)
- Use for: Documentation structure, formatting, rendering
- Validates: Extension docs, Core docs, any TYPO3 documentation
- URL: https://github.com/netresearch/typo3-docs-skill
This skill (typo3-core-contributions): Handles contribution workflow
- Use for: GitHub PR process, commit messages, review coordination

Example from real experience (Issue #105737):

✅ Core code fix → This skill → Gerrit submission (#91302)
✅ Documentation fix → This skill → GitHub PR (#397)
✅ Documentation validation → typo3-docs-skill → Format checking

When we fixed issue #105737:

Used this skill to submit Core code patch via Gerrit
Discovered docs error in commit message guide
Used this skill to create GitHub PR to TYPO3CMS-Guide-ContributionWorkflow
Could use typo3-docs-skill to validate reStructuredText formatting

When to use each skill:

typo3-core-contributions (this): For CONTRIBUTING to TYPO3 (code or docs)
typo3-docs-skill: For WRITING/VALIDATING documentation format

Workflow Decision Tree

Determine the user's current state and guide accordingly:

User starts contribution workflow
├─ Has Forge issue URL?
│  ├─ Yes → Proceed to Prerequisites Check
│  └─ No → Guide to Issue Creation Phase
├─ Prerequisites verified?
│  ├─ Yes → Proceed to Development Phase
│  └─ No → Guide through Setup Phase
├─ Patch ready?
│  ├─ Yes → Proceed to Submission Phase
│  └─ No → Guide through Development Phase
└─ Patch submitted?
   ├─ Yes → Guide through Review & Update Phase
   └─ No → Prepare for Gerrit submission

Prerequisites Check

Before beginning any contribution work, verify the user has:

Required Accounts:
- TYPO3.org account (my.typo3.org)
- Gerrit account with SSH keys (review.typo3.org)
- Slack access (typo3.slack.com) for #typo3-cms-coredev channel
Development Environment:
- Git configured with TYPO3 settings
- TYPO3 Core repository cloned
- DDEV-based development environment (preferred)
- Git hooks installed (commit-msg, pre-commit) - see references/commit-msg-hook.md for validation details
Skill Integrations:
- typo3-ddev-skill for environment management
- typo3-docs-skill for documentation contributions (optional)
- typo3-conformance-skill for code quality checks (optional)

Run scripts/verify-prerequisites.sh to check all prerequisites. If any are missing, proceed to the Setup Phase.

⚠️ Critical Email Requirement: Your Git email MUST match one of your registered Gerrit emails or all pushes will be rejected:

Check registered emails: https://review.typo3.org/settings#EmailAddresses
Verify Git config: git config user.email
If mismatch, update Git: git config user.email "your-registered@email.com"
This verification is included in verify-prerequisites.sh

Phase 1: Account Setup

Check Existing Accounts

Ask the user:

"Do you have a TYPO3.org account?"
"Have you set up Gerrit SSH access?"
"Are you in the TYPO3 Slack workspace?"

Guide Account Creation

If accounts are missing, load references/account-setup.md for detailed instructions:

TYPO3.org Account:

Visit https://my.typo3.org/index.php?id=2
Register with username, email, full name, and strong password
Verify email
This account provides access to Forge and Gerrit

Gerrit SSH Setup:

Sign in to https://review.typo3.org with TYPO3.org credentials
Generate SSH key pair (platform-specific instructions in reference)
Add public key to Gerrit: Profile → SSH Keys
Test connection: ssh -p 29418 <username>@review.typo3.org

Slack Access:

Join TYPO3 Slack: https://typo3.slack.com
Required channel: #typo3-cms-coredev
Optional channels: #typo3-cms, #random

Verify completion before proceeding to next phase.

Phase 2: Environment Setup

Quick Setup Options

Option 1: Automated Setup (Recommended for Beginners)

./scripts/setup-typo3-coredev.sh

Interactive script that guides through complete setup. See below for details.

Option 2: Use typo3-ddev-skill

Use typo3-ddev-skill for complete DDEV setup

If available, use the typo3-ddev-skill for guided setup.

Option 3: Manual Setup Follow the comprehensive workflow in references/ddev-setup-workflow.md for step-by-step instructions.

Automated Setup Script

The scripts/setup-typo3-coredev.sh script provides complete automated setup:

What it does:

Checks prerequisites (Git, DDEV, Docker)
Gathers configuration (project name, credentials, PHP version)
Clones TYPO3 Core repository
Configures Git for Gerrit submissions
Sets up DDEV with optimal settings
Installs dependencies and TYPO3
Activates development extensions
Generates test data (optional)

Usage:

cd /path/to/your/projects/
./path/to/scripts/setup-typo3-coredev.sh

Interactive prompts:

Project name (e.g., t3coredev-14-php8-4)
Your name for Git commits
Your email
Gerrit username
PHP version (8.2, 8.3, 8.4)
Timezone
TYPO3 admin password

The script handles all configuration and creates a fully functional development environment.

Manual DDEV Setup (If Automation Not Suitable)

If typo3-ddev-skill is not available and you prefer manual setup:

Clone TYPO3 Repository:

mkdir typo3-contribution && cd typo3-contribution
git clone git@github.com:typo3/typo3.git .

Configure Git for TYPO3:

# User identity (required)
git config user.name "Your Name"
git config user.email "your-email@example.org"

# Auto-rebase (required)
git config branch.autosetuprebase remote

# Gerrit push configuration (required)
git config remote.origin.pushurl ssh://<USERNAME>@review.typo3.org:29418/Packages/TYPO3.CMS.git
git config remote.origin.push +refs/heads/main:refs/for/main

Install Git Hooks:

composer gerrit:setup

Or manually copy from Build/git-hooks/ to .git/hooks/ and make executable.

Set Up Commit Template (optional but recommended): Copy assets/commit-template.txt to ~/.gitmessage.txt:

git config commit.template ~/.gitmessage.txt

Verify Setup

Run verification checks:

# Check git configuration
git config -l | grep -E "user\.|remote\.origin\.|branch\.autosetuprebase"

# Test Gerrit connection
ssh -p 29418 <username>@review.typo3.org

# Verify hooks exist
ls -la .git/hooks/commit-msg .git/hooks/pre-commit

All checks must pass before proceeding.

Phase 3: Issue Management

Working with Existing Forge Issue

If user provides a Forge issue URL (e.g., https://forge.typo3.org/issues/105737):

Fetch and analyze the issue:

Use WebFetch to extract:
- Issue title and description
- Issue number (e.g., #105737)
- Status and category
- Affected TYPO3 version
- Steps to reproduce
- Expected vs actual behavior
- Any existing patches or comments

Determine contribution scope:
- Bugfix → [BUGFIX] commit type
- New feature → [FEATURE] commit type (main branch only)
- Refactoring/cleanup → [TASK] commit type
- Documentation → [DOCS] commit type
- Security → [SECURITY] commit type
Check for existing patches:
- Search Gerrit: https://review.typo3.org
- Look for Change-Id or related patches
- Coordinate if others are working on it

Creating New Forge Issue

If user has a bug but no issue yet:

Gather issue information:
- What is broken or what feature is needed?
- Steps to reproduce (for bugs)
- Expected behavior vs actual behavior
- TYPO3 version affected
- Error messages or logs
Create issue on Forge:
- Visit https://forge.typo3.org/projects/typo3cms-core/issues/new
- Fill in all required fields
- Category: Choose appropriate area (Backend, Frontend, etc.)
- Priority: Should have (most common), Must have, Could have
- Set target version if known
Note the issue number for commit message later

Important: Every patch must have a matching Forge issue before submission.

Creating Forge Issues Programmatically (Advanced)

For automation or when web UI is not accessible, Forge issues can be created via the Redmine REST API:

Prerequisites:

Get API key from https://forge.typo3.org/my/account (under "API access key")
Store securely as environment variable: FORGE_API_KEY

Using the script:

# Set your API key
export FORGE_API_KEY="your-api-key-here"

# Create issue
./scripts/create-forge-issue.sh

The script interactively prompts for:

Subject line
Description
Tracker type (Bug, Feature, Task)
Category (e.g., Backend, Frontend, Indexed Search)
Priority (Should have, Must have, Could have)
TYPO3 version affected

Manual API usage:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Redmine-API-Key: $FORGE_API_KEY" \
  -d '{
    "issue": {
      "project_id": "typo3cms-core",
      "subject": "Issue title",
      "description": "Detailed description",
      "tracker_id": 1,
      "category_id": 975,
      "priority_id": 4,
      "custom_fields": [
        {"id": 4, "value": "13"}
      ]
    }
  }' \
  https://forge.typo3.org/issues.json

Common IDs (query full list via API):

Trackers: 1=Bug, 2=Feature, 4=Task
Priority: 3=Must have, 4=Should have, 5=Could have
Categories: Use scripts/query-forge-metadata.sh to list all categories

Response includes:

Created issue number (for Resolves: line)
Issue URL for reference

Load references/forge-api.md for complete API documentation and examples.

Phase 4: Development

Create Feature Branch

# Ensure on main branch with latest changes
git checkout main
git pull origin main

# Create feature branch (name pattern: feature/<issue-number>-<description>)
git checkout -b feature/105737-fix-indexed-search-crash

Make Code Changes

Guide the user through development:

Analyze the issue: Understand root cause and scope
Locate affected files: Use code search and navigation
Implement fix or feature:
- Follow TYPO3 coding standards
- Use framework patterns (DI, service locators, event dispatchers)
- Check if TYPO3 already provides the pattern you need
- Add/update documentation as needed
- Consider backwards compatibility
- Add deprecations properly with trigger_error() (no [!!!] for deprecations)
- For breaking changes: Document impact on extension developers

Real-world insight: Reviewers expect architectural alignment with TYPO3 framework patterns. Don't reinvent what the framework provides. Study Services.yaml patterns and use dependency injection over manual instance management.

Write tests:

Unit tests for isolated functionality
Functional tests for integrated behavior
Follow existing test patterns in codebase

Use typo3-testing-skill for comprehensive test writing:

Activate typo3-testing-skill for:
- Writing unit tests for new functionality
- Creating functional tests for integrations
- Understanding TYPO3 test patterns
- Setting up test fixtures and data
- Running and debugging tests locally

Build frontend assets (if needed):
- SCSS → CSS compilation
- JavaScript/TypeScript bundling
- Run build commands: npm run build or similar
Create changelog entries (if needed):
- Breaking changes require changelog
- New features should have changelog
- Location: Build/CHANGELOG/

Code Quality Validation

IMPORTANT: Always validate code quality BEFORE committing. Use typo3-conformance-skill:

Activate typo3-conformance-skill to:
- Check TYPO3 Coding Guidelines (CGL) compliance
- Run PHP_CodeSniffer (PHPCS) validation
- Execute PHPStan static analysis
- Validate PHP syntax and compatibility
- Fix coding standard violations automatically
- Ensure code passes CI checks locally

When to use:

✅ Before first commit
✅ After making code changes
✅ Before pushing to Gerrit
✅ When CI checks fail

Benefits:

Catch issues locally before submission
Faster review process (no back-and-forth on standards)
Learn TYPO3 coding conventions
Avoid CI pipeline failures

Self-Review

Before committing, review the changes:

Code follows TYPO3 conventions (validated with typo3-conformance-skill)
No debug statements or console.log
Tests pass locally (written/validated with typo3-testing-skill)
Documentation is updated
Changelog created if needed
No unintended file changes

Phase 5: Commit Creation

Commit Message Format

TYPO3 requires strict commit message formatting. Use scripts/create-commit-message.py for interactive generation, or follow this format:

Structure:

[TYPE] Subject line (max 52 chars, imperative mood)

Detailed description of changes explaining the how and why.
Lines wrapped at 72 characters. Use bullet points with * for
multiple items.

Resolves: #12345
Releases: main, 13.4, 12.4

Commit Types:

[BUGFIX] - Bug fixes
[FEATURE] - New features (main branch only)
[TASK] - Refactoring, cleanup, miscellaneous
[DOCS] - Documentation changes
[SECURITY] - Security fixes
[!!!] - Breaking change prefix (before type: [!!!][FEATURE])

Footer Tags:

Resolves: #<issue> (REQUIRED) - Every commit MUST have at least one Resolves line. The commit-msg hook will reject commits without it. Closes issue on merge for features/tasks.
Related: #<issue> (OPTIONAL) - Links related issues without closing. CANNOT be used alone - you must have at least one Resolves line in addition to any Related lines.
Releases: main, 13.4, 12.4 (REQUIRED) - Target versions (comma-separated)
Change-Id: I<hash> - Auto-generated by git hook (DO NOT modify, NEVER remove)

Subject Line Rules:

Maximum 52 characters (72 absolute limit)
Imperative mood: "Fix bug" not "Fixed bug" or "Fixes bug"
Start with uppercase letter
No period at the end
Describe what now works, not what was broken

Description Body:

Explain how and why, not what (code shows what)
Don't repeat Forge issue content
Don't describe reproduction steps
Keep focused on changes made
Wrap at 72 characters (URLs can be longer)

Load references/commit-message-format.md for complete specification with examples.

Create the Commit

Initial commit:

git add .
git commit
# Edit commit message in editor (template will load if configured)

The commit-msg hook automatically adds the Change-Id line - never modify or remove this!

Validate commit message: Run scripts/validate-commit-message.py to check format compliance.

Amending Commits

For subsequent changes to the same patch:

git add .
git commit --amend
# Preserve the Change-Id line!

Important: Keep only ONE commit on the branch. All changes should be amended into the single commit.

Phase 6: Gerrit Submission

First-Time Submission

Push to Gerrit:

git push origin HEAD:refs/for/main

Or simply git push if defaults are configured.

Expected response:

remote: SUCCESS
remote: https://review.typo3.org/c/Packages/TYPO3.CMS/+/12345 [NEW]

Copy and save the review URL!

Post-Submission Actions

Check Continuous Integration:
- Gerrit automatically runs tests
- Wait for CI results (usually 5-15 minutes)
- Green checkmarks = passed, red X = failed
Monitor for feedback:
- You'll receive email notifications
- Check Gerrit review page regularly
- Join #typo3-cms-coredev on Slack
Advertise your patch (optional, recommended for new contributors):
- Post in #typo3-cms-coredev: "I've submitted my first patch for issue #12345, would appreciate reviews: "

Phase 7: Review & Update Cycle

Understanding Review Expectations

IMPORTANT: Multiple revisions (patch sets) are NORMAL and expected in TYPO3 Core.

Real-world examples (from actual merged patches):

Extbase FileUpload tests: 24 patch sets
Record API breaking change: 14 patch sets
DI refactoring: 9 patch sets
Pagetree performance fix: 7 patch sets

What causes multiple revisions:

CI failures requiring fixes
Rebases due to main branch updates
Code quality improvements from reviewer feedback
Architectural refinements suggested by core team
Edge case handling
Scope adjustments (e.g., backport constraints)

Mindset: Each revision makes your patch better. High revision counts show:

Responsiveness to feedback
Collaborative improvement
Thorough vetting process
Learning framework patterns

Load references/gerrit-review-patterns.md for comprehensive real-world review insights.

Responding to Feedback

When reviewers request changes:

Read feedback carefully: Understand what needs to change
Respond to every comment: Even if just "Done" or "Fixed in PS X"
Make requested changes: Update code locally
Use appropriate skill:
- Code quality issues → typo3-conformance-skill
- Test failures → typo3-testing-skill
Test thoroughly: Validate changes work

Amend the commit:

git add .
git commit --amend
# Keep the Change-Id unchanged!

Push updated patch:
```
git push origin HEAD:refs/for/main
```

This creates a new patchset on the existing review.

Pro tip: Don't take high revision counts personally - they're a sign of thorough review, not failure.

Rebasing Your Patch

If your patch falls behind main branch:

Option 1: Browser-based (easiest):

Open your patch on Gerrit
Click "Rebase" button
Select "Rebase on top of the main branch"
Works only if no conflicts exist

Option 2: Command-line:

# Fetch latest changes
git fetch origin

# Rebase onto main
git rebase origin/main

# If conflicts occur, resolve them:
# 1. Fix conflicts in files
# 2. git add <resolved-files>
# 3. git rebase --continue

# Push rebased patch
git push origin HEAD:refs/for/main

Load references/gerrit-workflow.md for detailed rebase and conflict resolution procedures.

Review Process

Voting System:

Code Review: -2 (reject) to +2 (approve)
Verified: -1 (fails tests) to +1 (passes tests)
+2 from core team member + +1 verified → Ready for merge

Typical Timeline:

Simple bugfixes: 1-3 days
Complex features: 1-2 weeks
Patches need at least 2 reviewers (one must be core team)

Phase 8: Merge & Completion

Pre-Merge

Once approved:

Core merger will handle final merge
You'll receive notification when merged
Issue status updates automatically on Forge

Post-Merge

Clean up local branch:

git checkout main
git pull origin main
git branch -D feature/105737-fix-indexed-search-crash

Update Forge issue if needed:
- Add any follow-up notes
- Close related issues if applicable
Celebrate: You've contributed to TYPO3 Core! 🎉

Integration with Other Skills

This skill works best when combined with specialized TYPO3 skills. Activate them proactively during the contribution workflow.

typo3-ddev-skill

Purpose: DDEV-based development environment setup and management

When to activate:

Use typo3-ddev-skill when:
- Setting up TYPO3 Core development environment from scratch
- Configuring DDEV for TYPO3
- Managing local TYPO3 instances
- Database operations and management
- Troubleshooting DDEV/Docker issues

Integration point: Phase 2 (Environment Setup)

URL: Check if available in your environment

typo3-docs-skill

Purpose: TYPO3 documentation format validation and writing

When to activate:

Use typo3-docs-skill when:
- Writing TYPO3 documentation (Core or Extension)
- Validating reStructuredText (.rst) format and structure
- Checking documentation rendering locally
- Understanding TYPO3 documentation standards
- Fixing formatting issues in .rst files
- Creating proper cross-references and code blocks

Integration point: Phase 4 (Development) - for documentation contributions

Complementary usage: This skill handles the contribution workflow (GitHub PRs, commit messages), while typo3-docs-skill handles the documentation format itself.

URL: https://github.com/netresearch/typo3-docs-skill

typo3-conformance-skill

Purpose: TYPO3 Coding Guidelines (CGL) and code quality validation

When to activate (PROACTIVELY):

Use typo3-conformance-skill:
- BEFORE committing code changes
- After implementing new functionality
- When fixing coding standard violations
- Before pushing to Gerrit
- When CI checks fail

Validates:

TYPO3 Coding Guidelines (CGL) compliance
PHP_CodeSniffer (PHPCS) standards
PHPStan static analysis
PHP syntax and version compatibility
Best practices and patterns

Integration points:

Phase 4 (Development) - Code Quality Validation section
Phase 6 (Gerrit Submission) - Before pushing
Phase 7 (Review & Update) - When CI fails

Benefits:

Catch issues locally before submission
Avoid CI pipeline failures
Faster review process
Learn TYPO3 conventions

URL: https://github.com/netresearch/typo3-conformance-skill

typo3-testing-skill

Purpose: TYPO3 test writing and execution

When to activate (PROACTIVELY):

Use typo3-testing-skill when:
- Writing unit tests for new functionality
- Creating functional tests for integrations
- Writing acceptance/E2E tests
- Understanding TYPO3 test patterns and structure
- Setting up test fixtures and data providers
- Running and debugging tests locally
- Fixing failing tests
- Increasing test coverage

Covers:

Unit testing (PHPUnit)
Functional testing (database integration)
Acceptance testing (Codeception)
Test structure and organization
Mocking and fixtures
Test execution and debugging

Integration points:

Phase 4 (Development) - Writing Tests subsection
Phase 7 (Review & Update) - When tests fail
Before submission - Ensure tests pass

Benefits:

Write better, more maintainable tests
Understand TYPO3 testing patterns
Debug test failures effectively
Ensure adequate test coverage

URL: https://github.com/netresearch/typo3-testing-skill

Recommended Workflow with Skills

Complete workflow using all skills:

Setup → typo3-ddev-skill → Environment ready
Development → This skill → Feature branch created
Code Implementation → This skill → Code written
Testing → typo3-testing-skill → Tests written and passing
Quality Check → typo3-conformance-skill → CGL validated
Documentation (if applicable) → typo3-docs-skill → Docs formatted
Commit → This skill → Proper commit message
Submit → This skill → Gerrit/GitHub submission
Review → This skill → Handle feedback
Merge → This skill → Celebrate! 🎉

Common Scenarios

Scenario 1: Complete First Contribution

User: "I want to fix https://forge.typo3.org/issues/105737"

Workflow with skill integrations:

Run prerequisites check
Fetch issue details from Forge
Verify/setup accounts if needed
Use typo3-ddev-skill → Setup/verify environment
Create feature branch
Guide through fix development
Use typo3-testing-skill → Write unit/functional tests
Use typo3-conformance-skill → Validate code quality (CGL, PHPStan)
Create commit with proper message
Submit to Gerrit
Monitor review process

Proactive skill activation:

Activate typo3-testing-skill when writing tests (step 7)
Activate typo3-conformance-skill BEFORE committing (step 8)
These skills help catch issues locally, saving review cycles

Scenario 2: Update Existing Patch

User: "Reviewer asked me to change variable names in my patch"

Workflow with skill integrations:

Verify git setup and branch
Guide through changes
Use typo3-conformance-skill → Validate changes meet CGL
Amend commit (preserve Change-Id!)
Push updated patchset
Notify reviewer on Gerrit

Best practice: Always run typo3-conformance-skill after making changes to ensure new code still passes all quality checks.

Scenario 3: Rebase Needed

User: "My patch shows merge conflicts"

Workflow:

Load references/gerrit-workflow.md for conflict resolution
Guide through rebase process
Help resolve conflicts if needed
Test after rebase
Push rebased patch

Scenario 4: Create New Issue

User: "I found a bug in TYPO3 backend but there's no issue"

Workflow:

Gather bug details systematically
Check if issue already exists on Forge
Guide through Forge issue creation
Proceed with contribution workflow

Scenario 5: Root Cause Analysis and Dual-Repository Fix

User: "Documentation seems wrong, but the real issue is in the Core code"

Real Example from Issue #105737:

Initial symptom: Documentation mentioned both "Resolves:" and "Fixes:" tags
Investigation: Reviewer confirmed TYPO3 uses only "Resolves:" for standardization
Root cause discovery: commit-msg hook at Build/git-hooks/commit-msg:218 displayed misleading error message
Dual-repository solution:
- Documentation fix via GitHub PR to TYPO3CMS-Guide-ContributionWorkflow
- Core fix via Gerrit patch to update commit-msg hook error message
API usage: Created Forge issue #107881 via Redmine API
Backward compatibility: Kept validation regex accepting both, updated only user-facing message

Workflow:

Analyze whether issue is documentation-only or has Core source
If Core source exists:
- Create Forge issue for Core fix
- Submit Core patch via Gerrit (this skill)
- If docs also need update, create separate PR (typo3-docs-skill)
Ensure both fixes reference each other
Balance backward compatibility with standardization

Scenario 6: CI Pipeline Failures

User: "My patch was submitted but CI checks are failing"

Workflow with skill integrations:

Check Gerrit for CI failure details
Identify failure type:
- CGL/Coding Standards → Use typo3-conformance-skill
- PHPStan/Static Analysis → Use typo3-conformance-skill
- Unit/Functional Tests → Use typo3-testing-skill
- Build/Compilation → This skill for troubleshooting
Fix issues locally using appropriate skill
Validate locally BEFORE pushing:
- Run typo3-conformance-skill for code quality
- Run typo3-testing-skill for test execution
Amend commit with fixes
Push updated patchset

Pro tip: Use typo3-conformance-skill and typo3-testing-skill BEFORE first submission to avoid CI failures entirely. Catching issues locally is faster than waiting for CI pipelines.

Troubleshooting

Common issues and solutions:

"Permission denied" when pushing:

Check SSH key configuration
Test: ssh -p 29418 <username>@review.typo3.org
Verify pushurl: git config remote.origin.pushurl

"Missing Change-Id in commit message":

Install commit-msg hook: composer gerrit:setup
Or copy manually from Build/git-hooks/commit-msg
Re-commit with git commit --amend

"Merge conflict" during rebase:

Load references/gerrit-workflow.md for detailed steps
Resolve conflicts manually
Continue: git add . && git rebase --continue

"CI tests failing":

For code quality issues (CGL, PHPStan): Use typo3-conformance-skill
For test failures: Use typo3-testing-skill
Check specific failure details on Gerrit
Fix issues locally with appropriate skill
Validate locally before pushing updated patchset

"Coding standards violations":

Use typo3-conformance-skill immediately
Run PHPCS, PHPStan, and CGL checks locally
Fix violations automatically where possible
Learn TYPO3 conventions to avoid future violations

Load references/troubleshooting.md for comprehensive troubleshooting guide.

Resources

scripts/

setup-typo3-coredev.sh: Complete automated DDEV setup (recommended for new contributors)

./scripts/setup-typo3-coredev.sh

Interactive script that sets up complete TYPO3 Core development environment including Git configuration, DDEV, TYPO3 installation, and test data.

verify-prerequisites.sh: Check all prerequisites (accounts, git config, environment)

./scripts/verify-prerequisites.sh

create-commit-message.py: Interactive commit message generator following TYPO3 format

python scripts/create-commit-message.py --issue 105737 --type BUGFIX

validate-commit-message.py: Validate commit message against TYPO3 requirements

python scripts/validate-commit-message.py

create-forge-issue.sh: Create Forge issues via Redmine REST API (interactive)

export FORGE_API_KEY="your-api-key"
./scripts/create-forge-issue.sh

query-forge-metadata.sh: Query Forge for available categories, trackers, and priorities

export FORGE_API_KEY="your-api-key"
./scripts/query-forge-metadata.sh

references/

ddev-setup-workflow.md: Complete production-tested DDEV setup workflow (686 lines)

Step-by-step manual setup instructions
DDEV configuration details
TYPO3 installation and extension activation
Test data generation
Troubleshooting and best practices

account-setup.md: Detailed account creation guides (TYPO3.org, Gerrit, Slack)

commit-message-format.md: Complete commit message specification with examples

gerrit-workflow.md: Comprehensive Gerrit usage (review, rebase, conflicts, voting)

forge-api.md: Complete Forge/Redmine REST API documentation with examples

commit-msg-hook.md: Deep dive into Build/git-hooks/commit-msg validation and error messages

troubleshooting.md: Common issues and solutions

assets/

commit-template.txt: Git commit message template for TYPO3 (copy to ~/.gitmessage.txt)

Contribution Workflow Standards

Apply these standards throughout the contribution process:

When managing commits:

Maintain exactly one commit per patch (amend changes, never create multiple commits)
Preserve the auto-generated Change-Id line (never modify or remove it)
Validate code quality BEFORE committing using typo3-conformance-skill proactively
Write and execute tests locally using typo3-testing-skill before any submission
Always validate with typo3-conformance-skill before pushing to Gerrit

When maintaining patches:

Rebase regularly to keep patch current with main branch
Self-review all changes thoroughly before pushing
Respond to reviewer feedback promptly (within 2-3 days maximum)
Leverage complementary skills (typo3-ddev-skill, typo3-docs-skill) as needed
Request help in #typo3-cms-coredev Slack channel when blocked

When writing code:

Study existing code patterns in affected files before implementing
Follow TYPO3 framework patterns (DI, events, service configuration)
Use typo3-conformance-skill validation BEFORE every commit
Use typo3-testing-skill when writing ANY test (unit, functional, acceptance)
Use typo3-docs-skill for ALL documentation contributions

When handling CI failures:

Catch issues locally first to avoid CI failures entirely
Fix issues locally using appropriate skill before pushing updates
Never skip validation to make builds pass
Understand root cause before applying fixes

References

Contribution Guide: https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/
Forge: https://forge.typo3.org
Gerrit: https://review.typo3.org
Forger (search tool): https://forger.typo3.com
Slack: https://typo3.slack.com (#typo3-cms-coredev)

34 KiB Raw Permalink Blame History

TYPO3 Core Contributions

When to Use This Skill

Scope: TYPO3 Core Contributions (Code AND Documentation)

Core Code (typo3/typo3)

Core Documentation (TYPO3-Documentation/*)

Workflow Decision Tree

Prerequisites Check

Phase 1: Account Setup

Check Existing Accounts

Guide Account Creation

Phase 2: Environment Setup

Quick Setup Options

Automated Setup Script

Manual DDEV Setup (If Automation Not Suitable)

Verify Setup

Phase 3: Issue Management

Working with Existing Forge Issue

Creating New Forge Issue

Creating Forge Issues Programmatically (Advanced)

Phase 4: Development

Create Feature Branch

Make Code Changes

Code Quality Validation

Self-Review

Phase 5: Commit Creation

Commit Message Format

Create the Commit

Amending Commits

Phase 6: Gerrit Submission

First-Time Submission

Post-Submission Actions

Phase 7: Review & Update Cycle

Understanding Review Expectations

Responding to Feedback

Rebasing Your Patch

Review Process

Phase 8: Merge & Completion

Pre-Merge

Post-Merge

Integration with Other Skills

typo3-ddev-skill

typo3-docs-skill

typo3-conformance-skill

typo3-testing-skill

Recommended Workflow with Skills

Common Scenarios

Scenario 1: Complete First Contribution

Scenario 2: Update Existing Patch

Scenario 3: Rebase Needed

Scenario 4: Create New Issue

Scenario 5: Root Cause Analysis and Dual-Repository Fix

Scenario 6: CI Pipeline Failures

Troubleshooting

Resources

scripts/

references/

assets/

Contribution Workflow Standards

References

34 KiB

Raw Permalink Blame History