开发

From The Document Foundation Wiki
Jump to: navigation, search

如何参与其中

开发者和用户可以通过很多方式对 LibreOffice 开发做出贡献,项目欢迎每一个人。比如,用户可以通过试用软件的测试版本,举报和验证 bug撰写文档,为模板美工辞典,字典投稿等等。另外就是帮助推广 LibreOffice

开发者可以帮助改进 LibreOffice 的代码库。刚开始,巨大的代码库可能令您望而却步,不过目前文档正变得越来越好,而且您也可以从现任的开发者团队获得帮助。您可以从以下几个方面起步:

报告错误

报告错误并验证它们仍然存在对项目而言是非常有价值的贡献。这里有如何提交新 bug 的信息。

查找可解决的问题

现已收集一组简单 Hacks 可供您找到第一项任务。当然,bugtracker 中有 open issues其中有一些标记了 EasyHacks 以便于查找。还有一组已经有人开始编译的疯狂想法

用于收集改进默认用户体验的想法的页面也已开放:默认 UI 改进

增强功能与缺失特性列表

简单 Hacks 页面之外,还有其它几个增强功能和缺失特性的页面:

  • 一个疯狂构想列表包含了那些颠覆性的修改和其它缺失特性。
  • 一个页面专门收集那些和大型机构相关的特殊增强功能和缺失特性,这些机构的 IT 管理部门上对于部署和技术支持方面有特殊的要求。因此我们把它们反馈给我们的对 LibreOffice 的期望列在这个页面。如果你想要老板开心,帮我们修复它们吧!
  • 一个列表专门收集和默认用户体验相关的改进,在默认 UI 改进页面。
  • 一个页面列出了真的很低级的缺失特性和增强功能

准备 patch

首先,遵循 OpenOffice.org 代码编写样式以及通用代码转换(如变量命名格式等)非常有意义。

要准备可以发到开发邮件列表的 patch,假定您从未修改的 master 分支开始。步骤如下:

  • 按您的心意 hack 代码(如果您计划进行大修改,请考虑采用专用分支
  • 在本地将您的变更 commit 至 git。第一个选项添加所有已修改的文件,而第二个选项允许选择 commit 哪些文件:
    git commit -a
    ... 或者 ...
    git add <文件 1> <文件 2> ...
    git commit

    当您输入 commit 信息时,请在第一行写上变更的简明描述。第二行留空,然后您可以在第三行解释如何进行何种变更及其原因。
  • 创建将通过邮件发送 patch 文件。如果您在单个代码库中,您可以直接使用 git 获取,如这样根据您所在分支的最后一次变更生成差异文件:
    git format-patch HEAD~1
    
    如果您的变更较广,遍及多个代码库,您可以这样将所有代码库的变更生成为单个 patch:
    ./bin/g format-patch --suffix=-@REPO@.patch -o/home/me/用来存放我的_patch_的/某目录 origin/master..HEAD
    

可选途径:提供可 pull 的 git 分支

LibreOffice 采用 git 开发,意味着我们可以利用 git 提供的全部精彩功能。如:人们可准备可供 committer pullclone 的 git 分支。 如果您打算这样做,最好提前咨询任一位 committer 是否方便这样做。

使用 Git 开发 LibreOffice

Git 是一款分布式版本控制系统(DVCS)。它虽然简单,却不失为一款非常强大的系统。但如果您对 DVCS 不熟悉,它可能有些令您困惑。还好网上有不少用来学习 Git 的精品资源。如果您对它不熟悉,您应该访问 http://git-scm.com/ 。本文接下来的部分将假定您对 Git 的基本工作知识有所了解。

由于项目尺寸巨大,LibreOffice 的源码通过 19 个分开的 Git 代码库进行分发。这即使对酷爱 git 的用户也造成了挑战。

./bin/g

主要挑战之一便是您经常发现自己需要对全部 19 个代码库执行相同的 git 命令。 根代码库包含了一个实用小工具,名叫 g,位于 ./bin/g(路径随您的根 LibreOffice git 代码库而变化),或者假如您使用的是 bootstrap 版本,则位于 ./g

您可能输入的大部分命令如 git xxxx 可以这样输入 ./bin/g xxxx,意为“针对 ./clone/ 中所包含的所有代码库执行 git xxxx

默认情况下,对于大多数 git 命令,若在对任一 LibreOffice git 代码库执行命令的过程中出现错误,./bin/g 将停止运行,不会将命令应用到剩下的代码库。要覆盖该行为,您可以输入 ./bin/g -f xxxx

如果您使用的是 bootstrap 版本,可以直接将所有 ./bin/g 替换为 ./g,上文仍然可用。

简化 ./bin/g 使用

./bin/g 通常不在您的 PATH 路径中。当然,您可以将其加入您的 PATH,但那将使您无法拥有代码库的多个副本。 考虑到完成一次完整干净编译所需的时间,我更希望拥有代码库的另一份副本,在那里进行不受开发影响的操作。

PATH 不包括 ./bin/g 使得输入命令更冗长且易出错。下面的小脚本——可以 find-lo-bin 为名加入您的 PATH——可以解决该问题:

#!/bin/bash
current_dir=`pwd`
while [ ${current_dir} != "/" -a -d "${current_dir}" -a ! -d "${current_dir}/.git" ] ;
do
current_dir=$(dirname "${current_dir}")
done
if [ $(basename $(dirname ${current_dir})) = "clone" ] ; then
current_dir=$(dirname $(dirname "${current_dir}"))
fi
echo "${current_dir}/bin"
unset current_dir

现在您可以将它加入您的别名列表(如在您的 .bashrc 中)了:

alias g='$(find-lo-bin)/g'

这样您只需要输入“g xxxx”就能像在 LibreOffice 根代码库的目录中一样输入命令了。

./bin/g 的另一个限制是它只应用到 ./clone/ 中的 git 代码库,而不能应用到 git 根代码库本身。所以您通常需要输入 git xxx && ./bin/g xxx

下面名叫 'ga' 的小脚本则提供了该功能的封装:

#!/bin/bash
cd $(find-lo-bin)/..
if [ "$1" = "-f" ] ; then
shift
git "$@"
./bin/g -f "$@"
else
git "$@" && ./bin/g "$@"
fi
cd - > /dev/null

Grep 检索

您可以使用 git grep 替代 grep 对大型源码树进行更快的检索(仅检索受版本控制的文件)。 您也可以使用 g grepga grep 同时搜索所有 git 代码库。

另一个可选途径是使用基于网页的 opengrok 工具,它可能比在您自己的机器上搜索更快。

管理 git 分支

检查当前分支

要查看您的代码库当前处于哪个分支,请执行:

~/loroot $ ./g branch

这将列出各代码库的本地分支,其中当前活动的分支前标有 '*'。各代码库应报告相同的活动分支。

branch 命令后添加 -r 将显示远程代码库中可用的分支(如可用专用分支列表)。

切换到专用分支

让我们根据 origin/master 在所有 git 代码库新建一个专用分支 'feature/slicebread',这可以让您安全开发新功能:

~/loroot $ ./g checkout -b feature/slicebread origin/master

如果您再次显示活动分支,所有代码库都应报告 'feature/slicebread'。

如果您打算切换到已存在的专用分支,而不是创建新分支,请执行:

~/loroot $ ./g -f checkout -b feature/slicebread origin/feature/slicebread

这将创建跟踪远程分支 feature/slicebread 的本地分支 'feature/slicebread'。 -f 强制 bin/g 不中断地执行所有代码库,即使有些代码库没有该分支。

返回:如果您想回到 master 分支并删除本地分支,请确保您的代码库没有任何未 commit 的变更,然后先返回 master,然后删除您的本地分支 feature/slicebread

~/loroot $ ./g checkout master
~/loroot $ ./g -f branch -D feature/slicebread

在专用分支 hack 与 commit

现在您可以随心所欲地 hack 和编译了。不要对 commit 害羞。这些 commit 完全在本地,除非您发布,不会对其他人可见。如果您想使开发历史更加清洁,您以后随时可以重新组织或合并一些 commit。每个 commit 应包含一组互相相关的变更,并在 commit-log 信息中描述清楚。commit-log 信息的第一行必须为变更的简明(不多于 80 个字符)概要,然后如果需要,空一行并输入更详细的描述。

现在,您已经实现了新功能,或者取得了一些进展并希望获得一些反馈。

首先,由于 master 分支自您“剥离至专有分支”以来可能已有变更,您应该 rebase 变更,这样它们才能被应用到最新 masterHEAD

rebase,您需要确保已 commit 所有相关变更并已清理代码库,没有“pending”的变更。 然后这样返回 master 分支

~/loroot $ ./g checkout master

刷新您的 master 分支

~/loroot $ ./g pull -r

返回您的专用分支

~/loroot $ ./g checkout feature/slicebread

rebase

~/loroot $ ./g rebase origin/master

若有冲突,您需要先解决,然后继续 rebase 直到完成。

现在,该发布了。有两种情况。

如果您没有可 push 这些变更的 git 代码库组,并打算准备一组 patch 用来在开发邮件列表中发表供审校。

~/loroot $ ./g format-patch --suffix=-@REPO@.patch --output-dir=<输出目录> master..HEAD

这将在您指定的目录中为各 git 代码库的每次 commit 创建一个文件,附加代码库名称。然后您就可以将这些文件作为附件附加到发往邮件列表的邮件中。(Hack 想法:创建小封装,或者修改 ./bin/g 使生成的 patch 均存入指定目录,文件名中包括所属 git 代码库的名称)

如果您能够 push 到一组 git 代码库中,则

~/loroot $ ./g push origin feature/slicebread

有大量优秀的教程、书籍甚至还有视频讲解如何使用 git。强烈鼓励您去看看。 LibreOffice 的开发环境有 20 个 git 代码库,它们逻辑上是一个整体,但需要分别维护(所以才有了 gga 脚本)。

在稳定分支 hack 并 commit

稳定分支根据 master 或其他稳定分支创建,以为发布以及后续维护更新稳定代码库。beta 阶段只有几条规则

  • 允许任何 bug 修正
  • 允许 督导委员会批准的新功能
  • 允许更改翻译

发布候选阶段还有几条更严格的规则

  • 允许保存经他人审核的修正(见下文)
  • 允许更改翻译;建议在当地 l10n 邮件列表寻求审核

RC 阶段不要直接 commit 修正。而是请通过 libreoffice@lists.freedesktop.orgJean 邮件列表、个人信件、irc 或通过相关 bug 条目寻求其他开发者审核。修正应由审核者使用如下命令 commit:

git commit -s --author='作者名称 <作者@邮件.地址>'

将被您修改过的代码库重置为原始的“vanilla”代码库

~/loroot $ bin/g reset --hard origin/master

将舍弃您所有本地的更改(不论是否已 commit)并将您当前所处分支重置为远程代码库中的样子。

libreoffice 特定部分开发

automake/configure

当前情况下,有两个主要的 configure.in 文件,一个在顶层 build 目录下,还有一个在 libreoffice 子目录中。所有重要变更都应同时修改两个文件,因为顶层的文件用于系统中所有 patch 集都被合并入主代码库中后移除操作的参考。

编译系统默认参数当前存放于 <loroot>/build/distro-configs

当前子级 configure.in 中可用的配置选项仅限于顶级配置文件中所用的选项。

Hacking configure.in

开发 / Hacking 备注

TODO: add syntaxhighlight