typo3-core-contributions
npx machina-cli add skill netresearch/typo3-core-contributions-skill/typo3-core-contributions --openclawTYPO3 Core Contributions
Guide for TYPO3 Core contribution workflow from account setup to patch submission.
When to Use
- Forge issue URLs (e.g.,
https://forge.typo3.org/issues/105737) - Contributing patches, fixing TYPO3 bugs
- Gerrit review workflow, rebasing, CI failures
Prerequisites
scripts/verify-prerequisites.sh
Check: TYPO3.org account, Gerrit SSH, Git config (email must match Gerrit!)
Workflow Overview
- Setup: Account → Environment (
scripts/setup-typo3-coredev.sh) - Branch:
git checkout -b feature/105737-fix-description - Analyze Issue: Understand deeply before coding (see below)
- Develop: Implement, write tests, validate with typo3-conformance-skill
- Verify CI: Run full test suite locally, ensure all checks pass
- Commit: Follow format, include
Resolves: #<issue>+Releases: - Submit:
git push origin HEAD:refs/for/main(starts as WIP) - CI Check: Wait for Gerrit CI, fix ALL failures before marking ready
- Mark Ready: Remove WIP state only when all CI jobs pass
- Update: Amend + push (preserve Change-Id!)
- Verify Releases: After approval, test in all target branches
Phase 3: Analyze Issue Deeply
Before writing any code, thoroughly understand the problem:
- What is broken? - Identify the exact behavior vs expected behavior
- Why is it broken? - Trace the root cause in the codebase
- Reproduction steps - Document minimal steps to reproduce
- Affected versions - Check which branches have the issue (main, 13.4, 12.4)
- Related code - Review existing tests and similar implementations
- Edge cases - Consider what else might be affected
This analysis prevents wasted time on incomplete fixes or patches that don't address the actual problem.
Phase 5 & 8: CI Verification
Before marking ready for review:
- Run tests locally:
./Build/Scripts/runTests.sh -s unit && ./Build/Scripts/runTests.sh -s functional - Check code style:
./Build/Scripts/cglFixMyCommit.sh - Run PHPStan:
./Build/Scripts/runTests.sh -s phpstan - After push: Wait for ALL Gerrit CI jobs to complete
- Read actual job logs for any failures - never guess!
- Fix ALL issues in one patchset before marking ready
See references/gerrit-workflow.md for CI debugging details.
Phase 11: Verify in Target Branches
After receiving +2 approval, before merge:
- Check your
Releases:line (e.g.,main, 13.4, 12.4) - Cherry-pick to each target branch locally
- Verify fix works on each version
- Ensure no version-specific issues (API differences, etc.)
This prevents broken backports and ensures the fix works everywhere it's needed.
Commit Format
[TYPE] Subject line (imperative, max 52 chars)
Description explaining how and why.
Resolves: #12345
Releases: main, 13.4, 12.4
Types: [BUGFIX], [FEATURE], [TASK], [DOCS], [SECURITY], [!!!]
Related Skills
- typo3-ddev-skill: Development environment
- typo3-testing-skill: Test writing
- typo3-conformance-skill: Code quality validation
References
| Topic | File |
|---|---|
| Account setup | references/account-setup.md |
| Commit format | references/commit-message-format.md |
| Gerrit workflow | references/gerrit-workflow.md |
| Troubleshooting | references/troubleshooting.md |
Contributing: https://github.com/netresearch/typo3-core-contributions-skill
Source
git clone https://github.com/netresearch/typo3-core-contributions-skill/blob/main/skills/typo3-core-contributions/SKILL.mdView on GitHub Overview
This skill guides the TYPO3 Core contribution workflow from setting up your account to submitting patches. It covers Forge issues, Gerrit reviews, CI validation, and updating documentation in TYPO3 Core.
How This Skill Works
Verify prerequisites with scripts/verify-prerequisites.sh, set up the dev environment using scripts/setup-typo3-coredev.sh, and iterate patches through Gerrit using the refs/for/main workflow. The process emphasizes issue analysis, development with tests, local CI validation, and incremental patch updates until all CI checks pass.
When to Use It
- When you have a TYPO3 Forge issue URL (e.g., https://forge.typo3.org/issues/105737)
- When contributing patches to TYPO3 Core or fixing core bugs
- During the Gerrit review workflow, including rebasing and addressing CI failures
- When contributing documentation updates to TYPO3 Core
- When ensuring commits follow the required format (Resolves: #<issue>, Releases:...)
Quick Start
- Step 1: Verify prerequisites and set up the dev environment with scripts/verify-prerequisites.sh and scripts/setup-typo3-coredev.sh
- Step 2: Create a feature branch (e.g., git checkout -b feature/105737-fix-description)
- Step 3: Submit to Gerrit and monitor CI (git push origin HEAD:refs/for/main); fix issues and push again as needed
Best Practices
- Verify prerequisites and ensure your TYPO3.org account, Gerrit SSH, and Git config email all align
- Create a feature branch with a descriptive name (e.g., feature/105737-fix-description)
- Develop with tests and validate using typo3-conformance-skill
- Run the full local test suite and fix all issues in one patchset before pushing
- Preserve Change-Id when amending commits and pushing updates to Gerrit
Example Use Cases
- Submit a patch to fix a TYPO3 core bug linked to a Forge issue
- Provide documentation updates to TYPO3 Core alongside code changes
- Rebase and rework a patch after CI failures and push a revised patchset
- Validate changes with local tests and the typo3-conformance-skill before submission
- After approval, verify releases across main, 13.4, and 12.4 branches
