typo3-core-contributions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

TYPO3.org Account: Register at https://my.typo3.org/
Gerrit SSH Key: Upload to https://review.typo3.org/settings/#SSHKeys
Git Config: Email must match your Gerrit account

bash

undefined

在开始贡献前，请确保你已具备以下条件：

TYPO3.org账户：在https://my.typo3.org/注册
Gerrit SSH密钥：上传至https://review.typo3.org/settings/#SSHKeys
Git配置：邮箱需与你的Gerrit账户匹配

bash

undefined

Verify git config

验证Git配置

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

Or clone from GitHub (read-only mirror)

或从GitHub克隆（只读镜像）

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. 查找或创建议题

Check existing issues: https://forge.typo3.org/projects/typo3cms-core/issues
Create new issue if needed with detailed description

查看现有议题：https://forge.typo3.org/projects/typo3cms-core/issues
如需创建新议题，请提供详细描述

2. Create Feature Branch

2. 创建功能分支

bash

undefined

bash

undefined

Update main branch

更新主分支

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

类型说明

Type	Description
`[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

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

Rebase

执行变基

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

Cherry-pick with original Change-Id

Cherry-pick并保留原Change-Id

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

评审状态

Vote	Meaning
+2	Approved, ready for merge
+1	Looks good, needs second review
0	Comment only
-1	Changes needed
-2	Major issues, do not merge

投票	含义
+2	批准，可合并
+1	代码可行，需二次评审
0	仅评论，无投票
-1	需要修改
-2	存在重大问题，禁止合并

CI Requirements

CI要求

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/

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

Resolve conflicts

解决冲突

Edit conflicting files

编辑冲突文件

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失败

Check CI output at review.typo3.org
Run tests locally:

bash

undefined

在review.typo3.org查看CI输出
本地运行测试：

bash

undefined

Run specific test suite

运行指定测试套件

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

Resources

参考资源

Gerrit: https://review.typo3.org/
Forge: https://forge.typo3.org/
Contribution Guide: https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/
Git Setup: https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/Setup/Git/

Gerrit：https://review.typo3.org/
Forge：https://forge.typo3.org/
贡献指南：https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/
Git设置：https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/Setup/Git/

Credits & Attribution

致谢与归属

Thanks to Netresearch DTT GmbH for their contributions to the TYPO3 community.

感谢Netresearch DTT GmbH对TYPO3社区的贡献。