Jump to content

如何成为MediaWiki黑客

本頁使用了標題或全文手工轉換
From mediawiki.org
This page is a translated version of the page How to become a MediaWiki hacker and the translation is 99% complete.

这篇文章用以帮助开发者学习开发MediaWiki内核和MediaWiki扩展的基础技能。

给MediaWiki做贡献常常是一件难事,所以如果你想参与维基媒体的开发,你应该给那些有新手指导的维基媒体项目做贡献。 想不靠新手指导的话,也可以选择修个适合上手的漏洞。

如果你是一个有经验的开发者,已经熟悉了使用MediaWiki,请访问开发者中心 。

对于其他参与维基媒体社区的方式,参见如何贡献 。

概覽

MediaWiki是驱动维基百科及其姊妹项目,以及全世界数以千计的wiki网站的软件。

MediaWiki及扩展大部分以PHP编程语言编写。 JavaScript用于提供交互界面元素,配合jQuery和Vue.js作为客户端JavaScript库。

某些支持工具由其他语言写成,包括批处理文件、外壳脚本、makefile和Python。

MediaWiki主要为LAMP平台编写,[1]并且能在大多数操作系统中运行。 MediaWiki主要使用MySQL或MariaDB数据库服务器。[2]

开发为开源形式,[3]协调大多在网上完成,并受到维基媒体基金会的支持,而志愿者社群也发挥了巨大作用。

寻找或创建任务

在你给MediaWiki项目开发功能或修复漏洞之前,做好你自己的研究工作非常重要。 这包括:

  1. 在Phabricator搜索是否已有开放或关闭的任务。 如果没有,就创建一个。 如果是很小的改动,就不用创建了。
  2. 寻找并调查实现功能所需要更改的代码。 如果你的发现有助于其他人实现功能或审核你的更改,可在Phabricator任务中评论。
  3. 基于你调查的代码和需要的更改,判断你是否有可能添加功能或修复漏洞。 如果任务量庞大或繁重,你应该先找点更简单的事情做,一步一步地进展,直到能处理那样大小的任务。 如果你相信自己能完成,就把任务分派给自己然后开始动手处理。

配置您的开发环境

一旦你找到自己能处理的事,开发MediaWiki或扩展的下一步就是创建一个环境用来运行MediaWiki、其数据库、以及其他外部功能,这样你就能开发并测试它们了。

你可以从以下三种方案任择其一,在Linux、Windows或macOS安装并开发MediaWiki。

Docker

如果你想快速搭建MediaWiki,不打算安装太多扩展,Docker是个不错的选择。 MediaWiki Docker为搭建容器化MediaWiki环境提供了一个简单的方式,你可以将其用于基础的测试。 如果你使用MediaWiki Docker遇到了运行缓慢,在本地安装可能是更好的选择。

你也可以试试mwcli工具,只用几条简单的命令就能搭建起Docker,并且提供MediaWiki、MySQL、ElasticSearch、Memcached和其他种类容器之间的基础统筹功能。

本地安装

如果你想不用Docker就快速搭建简单的开发环境,本地安装是个不错的选择。 本地安装可以帮助你学习MediaWiki的运作方式并从贡献者身份开始做起。

Vargant

Vagrant允许你启动一个可以开发的MediaWiki实例,同时能让你添加和开发250多种扩展——一切只需一条命令。

相比于在Docker或本地安装手动添加扩展,这能节省你安装和配置的时间,不过运行速度比其他两个做法慢。

打开一个代码编辑器

对于编辑MediaWiki,有两个推荐的代码编辑器:VSCode和PhpStorm 。 VSCode免费,PhpStorm收费,不过如果你是学生,你可以有以下方法免费获取PhpStorm的免费许可证:将你的GitHub教育版账号绑定到JetBrains账号,或者从维基媒体申请一个许可证。

要决定该安装使用哪个编辑器的话,记住,PhpStorm全方面地拥有比VSCode更多、更强的功能。 但是PhpStorm启动用时显著长于VSCode,因为PhpStorm要构建整个仓库的索引,而VSCode只是逐步加载。 因此,VSCode通常用于查看文件或微小改动,PhpStorm则用于更大的改动。 出于这些原因,两个都安装是合理的。

欲开发Docker容器内的MediaWiki代码库,你可以建立一个到容器的远程连接,并使用VSCode或PhpStorm打开其中的MediaWiki文件夹。

更改并测试代码

更改代码,然后重新加载你的MediaWiki浏览器标签页,查看更改。确保遵守Manual:代码编写约定 。 在你的代码上编写并运行测试,确保代码奏效,格式适当。

注意,在花时间写测试之前确认你的更改将被接受,你便可节省时间。 创建一个没有所需测试的补丁,请别人来审核,并指出你会在他们审核完之后添加测试。

创建补丁

最后,欲提交你的代码给他人审查并加入你贡献的仓库,请遵循Gerrit/教程 。

After your code has been submitted to Gerrit, you may opt to create a live demo of your changes using Patch demo and share it with reviewers. Creating a live demo is optional step.

沟通技巧和准则

一个开发者修复MediaWiki扩展漏洞的过程,包括调查、执行git commit、审查、合并、关闭Bugzilla(现由Phabricator 取代)工单等环节。

这些技巧能让你有效地与他人沟通,得到社区中其他成员的帮助。

高效率地使用Phabricator任务

当您准备着手处理一个Phabricator 任务时:

  • 无需请求许可: 您无需请求任何人将任务分配给您即可开始进行任务。 不存在谁能分配任务或是需要先问谁的权威人士。
    • 如果一个任务在Gerrit中已经有了一个最近的补丁,请选择一个不同的任务作為替代。
    • 如果Gerrit中的一个现有补丁還没有被合并,而且很长时间都没有任何改动,你可以根据Gerrit裏和任务裏的反馈,改进那個现有补丁。
  • 自行研究: 当您考虑进行某个任务时,在开始敲代码前先研究一番。仔細看看代码,試著去理解这些代码本该达到什么目的,閱讀相關的文件,然后尽量找到应该作出修改的地方。
    • 在一個Phabricator 任务中,使用侧边栏中的项目标签,找到任务的代码库。
    • 如果您对修复某个漏洞的办法毫无头绪,考虑先找个更简单的。
  • 你不需要在开始工作之前宣佈你的计划,但你应该传达你正在进行的任务。
    • 当你开始工作时,通过点击Phabricator中的“编辑任务…”(Edit Task…)将自己设置为任务受派人,并在“分派给”(Assigned To)字段中设置你的Phabricator用户名。 这就向其他人传达了你正在工作,所以他们不会重复工作。
    • 当你的计划或兴趣改变时: 如果你不再从事某项工作,请将你自己从任务的受派人删除。 这告诉其他人,他们可以从事这项工作,而他们不会期望你仍然在从事这项工作。
  • 遵守Phabricator礼仪。
    • 在Phabricator任务中,只讨论有关该任务主题的具体问题。 別拿Phabricator来问一般的问题,比如如何建立一个开发环境或如何修复Gerrit的问题。
    • 不要发表“请审核我的补丁”或“我提交了一个补丁,链接在此”之类的评论。 如果你的提交消息有正确的格式 ,补丁就会自动链接到任务,而且发表补丁已经隐含了审核请求,所以显式陈述请求添不了任何作用。

撰写好的问题

  • 别问能不能问问题……直接问问题!。
  • 要具体,并提供來龍去脈: 不要只是简单地问:「你能给我更多信息吗?」、「请指导我」、或「请告诉我如何开始」,而是在你的问题中包括以下信息:
    • 你想要达到什么?
    • 你已經試過什麼? 复制和粘贴你的命令和它们的输出(如果不是太长),而不是用你自己的话进行转述。
    • 在你的研究中,你已经发现了什么? 包括代码的链接、文档的链接、或其他你已经咨询过的资源的链接。
  • 在你的通信中使用具体的标题和主题行。 「提案的草案」或「我需要帮助」并不具体。
  • 保持对话的可读性: 当你在Zulip、Phabricator任务或邮件列表中回复时,只引用与你的回复相关的先前评论部分。 如果你引用一整個「完整的」以前的评论,会使讨论串难以阅读。

遵循沟通政策與最佳做法

在你发送或张贴你的问题之前:

在正确的地方提问

  • 公开询问:如果你谈话的主题不是什麼秘密,就不要发送私信。 私信帮不到其他人。
  • 在最好的地方提问和讨论:
    • 在Phabricator任务中,只讨论有关该任务主题的具体问题。
    • 在联系交流 列出的地方询问一般的技术问题,例如如何建立一个开发环境,或如何解决Gerrit的问题。
    • 如果你参加了拓展计划,那么Zulip是用来讨论关于拓展计划本身的问题。

请耐心等待

在你发布你的问题之后:

  • 不要在单独的信息中要求别人进行代码审查。 人们会收到Gerrit和Phabricator的通知,并会在他们可以的时候做出回应。
  • 在征求意见和评论时,特别是在周末和节假日,你可能需要等到恢复工作时间。 在像IRC这样的聊天频道中:如果没有人回答,在不同的时间再试一次;別这样就放弃了。
  • 如果你在等待和耐心等待之后仍然没有得到答案,请考虑其他沟通渠道是否是一个更好的地方来提出你的问题。

附录

MediaWiki贡献者在印度班加罗尔办公。

PHP

MediaWiki由PHP编写,所以你需要了解并熟悉PHP才可以熟练使用MediaWiki的核心代码。

學習PHP
  • PHP指导 – 在许多不同语言中都可用。 如果你完全不会PHP,但是知道在其他面向对象编程语言中如何编程,那么PHP对你来说会易学一些。
  • 维基教科书上的PHP编程。
  • 维基学院上的PHP。
PHP资源
需要知道的东西
  • MediaWiki中的脚本maintenance/eval.php提供了一个基本的包含MediaWiki对象与分级的PHP编译器。
  • 此外,MediaWiki中的脚本maintenance/shell.php是基于PsySH的maintenance/eval.php的替代,参见手册:Shell.php

資料庫

许多特性需要对数据库做出一定程度的修改,所以你常常需要熟悉MySQL/MariaDB。

学习MySQL或MariaDB
MySQL/MariaDB资源
要知道的东西
  • 用MySQL/MariaDB測試你的代碼。
    • MediaWiki目前使用MySQL和MariaDB作为主数据库后端。 它同样支持其他DBMS,例如PostgreSQL和SQLite。 但是,几乎所有开发人员都使用MySQL/MariaDB而不测试其他数据库,因此会定期中断。 因此,建议您在测试补丁时使用MySQL/MariaDB,除非您专门尝试改进对其他数据库的支持。 在后一种情况下,请确保您小心不要破坏MySQL/MariaDB(或编写非常低效的查询),因为MySQL/MariaDB是其他人使用的。

JavaScript和CSS

JavaScript和CSS在前端代码中无处不在。 您不必熟悉使用MediaWiki的JavaScript、jQuery和CSS,但您可能需要,具体取决于您选择的工作方式。

学习JavaScript和CSS
JavaScript和CSS资源

MediaWiki

MediaWiki核心概念介绍

MediaWiki代码库很大,有些部分很难看,不要被它淹没。 当您第一次开始时,目标是编写功能或修复只触及一小部分代码的错误。

MediaWiki基礎知識和必讀內容
MediaWiki资源

MediaWiki扩展

MediaWiki扩展介绍

如您选择在MediaWiki扩展的代码建设上添砖加瓦,下列链接能提供更多信息。

MediaWiki擴充功能基礎知識:
MediaWiki扩展手册:

MediaWiki皮肤

如果你选择从事MediaWiki皮肤,手册:如何制作MediaWiki皮肤 会有所帮助。

参阅

脚注

  1. ↑ MediaWiki在多数支持PHP的平台上都能运行,但在非LAMP上,MediaWiki的表现与功能可能会因为特定操作系统属性与特定实用工具的缺失大打折扣。
  2. ↑ MediaWiki还支持DBMS,包括PostgreSQL和SQLite
  3. ↑ 开发者中既有志愿者,也有各种组织的受薪员工(或合同工)。MediaWiki代码工作者的完整名单见开发人员 。
  4. ↑ 在 https://phabricator.wikimedia.org/diffusion/ 浏览源码和代码仓库的修订,也可以用Gerrit将源码下载到你的电脑。