Back to Details

typo3-core-contributions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TYPO3 Core Contributions Skill

TYPO3 Core Contributions Skill

Guide for TYPO3 Core contribution workflow from account setup to patch submission.
TYPO3 API First: Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Do not reinvent what TYPO3 already provides. Always verify that the APIs and methods you use exist and are not deprecated in your target TYPO3 version (v13 or v14) by checking the official TYPO3 documentation.
本指南介绍从账户设置到补丁提交的TYPO3核心代码贡献全流程。
TYPO3 API优先原则： 在实现自定义功能前，请优先使用TYPO3的内置API、核心功能和既定规范，不要重复造轮子。请务必通过官方TYPO3文档确认你使用的API和方法在目标TYPO3版本（v13或v14）中存在且未被弃用。

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
  • Forge议题链接（例如：
    https://forge.typo3.org/issues/105737
    ）
  • 贡献补丁、修复TYPO3漏洞
  • Gerrit评审工作流、变基操作、CI失败排查

Prerequisites

前置条件

Before contributing, ensure you have:
  1. TYPO3.org Account: Register at https://my.typo3.org/
  2. Gerrit SSH Key: Upload to https://review.typo3.org/settings/#SSHKeys
  3. Git Config: Email must match your Gerrit account
bash
undefined
在开始贡献前，请确保你已具备以下条件：
  1. TYPO3.org账户：在https://my.typo3.org/注册
  2. Gerrit SSH密钥：上传至https://review.typo3.org/settings/#SSHKeys
  3. Git配置：邮箱需与你的Gerrit账户匹配
bash
undefined

Verify git config

验证Git配置

git config --global user.name "Your Name" git config --global user.email "your.email@example.com"
git config --global user.name "Your Name" git config --global user.email "your.email@example.com"

Add Gerrit remote

添加Gerrit远程仓库

git remote add gerrit ssh://your-username@review.typo3.org:29418/Packages/TYPO3.CMS.git
undefined
git remote add gerrit ssh://your-username@review.typo3.org:29418/Packages/TYPO3.CMS.git
undefined

Environment Setup

环境搭建

Clone TYPO3 Core

克隆TYPO3核心代码仓库

bash
undefined
bash
undefined

Clone via Gerrit

通过Gerrit克隆

git clone ssh://your-username@review.typo3.org:29418/Packages/TYPO3.CMS.git cd TYPO3.CMS
git clone ssh://your-username@review.typo3.org:29418/Packages/TYPO3.CMS.git cd TYPO3.CMS

Or clone from GitHub (read-only mirror)

或从GitHub克隆（只读镜像）

git clone https://github.com/TYPO3/typo3.git cd typo3
git clone https://github.com/TYPO3/typo3.git cd typo3

Add Gerrit remote for pushing

添加Gerrit远程仓库用于推送

git remote add gerrit ssh://your-username@review.typo3.org:29418/Packages/TYPO3.CMS.git
undefined
git remote add gerrit ssh://your-username@review.typo3.org:29418/Packages/TYPO3.CMS.git
undefined

Install Commit Hook

安装提交钩子

bash
undefined
bash
undefined

Install commit-msg hook for Change-Id

安装用于生成Change-Id的commit-msg钩子

scp -p -P 29418 your-username@review.typo3.org:hooks/commit-msg .git/hooks/ chmod +x .git/hooks/commit-msg
undefined
scp -p -P 29418 your-username@review.typo3.org:hooks/commit-msg .git/hooks/ chmod +x .git/hooks/commit-msg
undefined

Contribution Workflow

贡献工作流

1. Find or Create Issue

1. 查找或创建议题

2. Create Feature Branch

2. 创建功能分支

bash
undefined
bash
undefined

Update main branch

更新主分支

git checkout main git pull origin main
git checkout main git pull origin main

Create feature branch

创建功能分支

git checkout -b feature/105737-fix-cache-issue
undefined
git checkout -b feature/105737-fix-cache-issue
undefined

3. Implement Changes

3. 实现代码变更

  • Follow TYPO3 coding guidelines
  • Write tests (unit, functional)
  • Update documentation if needed
  • 遵循TYPO3编码规范
  • 编写测试（单元测试、功能测试）
  • 如需更新文档，请同步修改

4. Commit with Proper Format

4. 按照规范提交代码

bash
git add .
git commit
Commit Message Format:
[TYPE] Subject line (imperative, max 52 chars)

Description explaining how and why the change was made.
Can be multiple paragraphs.

Resolves: #12345
Releases: main, 13.4
bash
git add .
git commit
提交信息格式：
[TYPE] 主题行（命令式语气，最多52个字符）

详细说明变更的原因和实现方式，可分为多个段落。

Resolves: #12345
Releases: main, 13.4

5. Push to Gerrit

5. 推送到Gerrit

bash
undefined
bash
undefined

Push for review

推送代码以进行评审

git push gerrit HEAD:refs/for/main
undefined
git push gerrit HEAD:refs/for/main
undefined

Commit Message Format

提交信息格式规范

Types

类型说明

TypeDescription
[BUGFIX]
Bug fix
[FEATURE]
New feature
[TASK]
Refactoring, cleanup, maintenance
[DOCS]
Documentation only
[SECURITY]
Security fix (coordinate with security team)
[!!!]
Breaking change prefix (e.g., 
[!!!][TASK]
)
类型说明
[BUGFIX]
漏洞修复
[FEATURE]
新功能
[TASK]
代码重构、清理、维护
[DOCS]
仅修改文档
[SECURITY]
安全修复（需与安全团队协作）
[!!!]
破坏性变更前缀（例如：
[!!!][TASK]
）

Required Footer

必需的页脚信息

Resolves: #12345
Releases: main, 13.4
  • Resolves:
    - Issue number on forge.typo3.org
  • Releases:
    - Target branches (main, 13.4, 12.4)
Resolves: #12345
Releases: main, 13.4
  • Resolves:
    - forge.typo3.org上的议题编号
  • Releases:
    - 目标分支（main, 13.4, 12.4）

Example Commit Messages

提交信息示例

Bug Fix:
[BUGFIX] Fix cache invalidation for page translations

The cache was not properly invalidated when updating
translated page properties. This patch ensures the
cache is cleared for all language variants.

Resolves: #105737
Releases: main, 13.4
Breaking Change:
[!!!][TASK] Remove deprecated DataHandler hooks

The legacy hooks have been deprecated since v12 and
are now removed. Use PSR-14 events instead.

See migration guide in the documentation.

Resolves: #98765
Releases: main
漏洞修复：
[BUGFIX] 修复页面翻译的缓存失效问题

当更新翻译后的页面属性时，缓存未被正确失效。本补丁确保所有语言变体的缓存都会被清除。

Resolves: #105737
Releases: main, 13.4
破坏性变更：
[!!!][TASK] 移除已弃用的DataHandler钩子

这些遗留钩子自v12版本起已被弃用，现正式移除。请改用PSR-14事件。

请参考文档中的迁移指南。

Resolves: #98765
Releases: main

Gerrit Workflow

Gerrit工作流

Update Existing Patch

更新现有补丁

When changes are requested:
bash
undefined
当收到修改请求时：
bash
undefined

Make changes

进行代码修改

...

...

Amend commit (keep same Change-Id!)

追加提交（保留原Change-Id！）

git add . git commit --amend
git add . git commit --amend

Push again

重新推送

git push gerrit HEAD:refs/for/main
undefined
git push gerrit HEAD:refs/for/main
undefined

Rebase on Latest Main

基于最新主分支变基

bash
undefined
bash
undefined

Fetch latest

获取最新代码

git fetch origin main
git fetch origin main

Rebase

执行变基

git rebase origin/main
git rebase origin/main

Force push (allowed for your own patches)

强制推送（仅允许推送你自己的补丁）

git push gerrit HEAD:refs/for/main --force
undefined
git push gerrit HEAD:refs/for/main --force
undefined

Cherry-pick to Other Branches

Cherry-pick到其他分支

After approval on main:
bash
undefined
在主分支上的补丁获得批准后：
bash
undefined

Switch to target branch

切换到目标分支

git checkout 13.4 git pull origin 13.4
git checkout 13.4 git pull origin 13.4

Cherry-pick with original Change-Id

Cherry-pick并保留原Change-Id

git cherry-pick -x <commit-hash>
git cherry-pick -x <commit-hash>

Push for review

推送以进行评审

git push gerrit HEAD:refs/for/13.4
undefined
git push gerrit HEAD:refs/for/13.4
undefined

Code Review

代码评审

Review States

评审状态

VoteMeaning
+2Approved, ready for merge
+1Looks good, needs second review
0Comment only
-1Changes needed
-2Major issues, do not merge
投票含义
+2批准，可合并
+1代码可行，需二次评审
0仅评论，无投票
-1需要修改
-2存在重大问题，禁止合并

CI Requirements

CI要求

All patches must pass:
  • Coding standards (PHP-CS-Fixer)
  • PHPStan level 8
  • Unit tests
  • Functional tests
  • Acceptance tests (if applicable)
所有补丁必须通过以下检查：
  • 编码规范（PHP-CS-Fixer）
  • PHPStan level 8
  • 单元测试
  • 功能测试
  • 验收测试（如适用）

Troubleshooting

故障排查

Push Rejected

推送被拒绝

bash
undefined
bash
undefined

Missing Change-Id

缺少Change-Id

Ensure commit hook is installed

确保已安装提交钩子

scp -p -P 29418 your-username@review.typo3.org:hooks/commit-msg .git/hooks/
scp -p -P 29418 your-username@review.typo3.org:hooks/commit-msg .git/hooks/

Amend to add Change-Id

追加提交以添加Change-Id

git commit --amend
undefined
git commit --amend
undefined

Merge Conflicts

合并冲突

bash
undefined
bash
undefined

Rebase on latest

基于最新代码变基

git fetch origin main git rebase origin/main
git fetch origin main git rebase origin/main

Resolve conflicts

解决冲突

Edit conflicting files

编辑冲突文件

git add . git rebase --continue
git add . git rebase --continue

Push updated patch

推送更新后的补丁

git push gerrit HEAD:refs/for/main --force
undefined
git push gerrit HEAD:refs/for/main --force
undefined

CI Failures

CI失败

  1. Check CI output at review.typo3.org
  2. Run tests locally:
bash
undefined
  1. 在review.typo3.org查看CI输出
  2. 本地运行测试：
bash
undefined

Run specific test suite

运行指定测试套件

Build/Scripts/runTests.sh -s unit Build/Scripts/runTests.sh -s functional
Build/Scripts/runTests.sh -s unit Build/Scripts/runTests.sh -s functional

Run PHP-CS-Fixer

运行PHP-CS-Fixer检查

Build/Scripts/runTests.sh -s cgl
undefined
Build/Scripts/runTests.sh -s cgl
undefined

Related Skills

相关技能

  • typo3-ddev: Local development environment
  • typo3-testing: Writing tests for patches
  • typo3-conformance: Code quality validation
  • typo3-ddev：本地开发环境
  • typo3-testing：为补丁编写测试
  • typo3-conformance：代码质量验证

Resources

参考资源

Credits & Attribution

致谢与归属

Thanks to Netresearch DTT GmbH for their contributions to the TYPO3 community.
感谢Netresearch DTT GmbH对TYPO3社区的贡献。