开发 / 参与

    From The Document Foundation Wiki
    This page is a translated version of the page Development/GetInvolved and the translation is 52% complete.


    文档基金会 LibreOffice官网 Document Liberation 项目 社区博客 Weblate翻译 Nextcloud Redmine Ask LibreOffice 问答 捐助

    Other languages:

    开发者和用户可以通过各种方式参与到LibreOffice项目中，我们欢迎每个人对该项目的贡献。

    用户可以参与的领域包括：通过使用软件的测试版本来发现并报告 bug，从而协助软件开发工作；编写文档；贡献模板；更新同义词库和字典, 将软件翻译成您的母语；美化；向全世界推 LibreOffice。

    这个页面上的内容主要针对开发者。我们对所有级别的开发者开放。LibreOffice 是世界上最大、最古老、最有名气（对于 OpenOffice）的软件之一。如果您是一名学生，或者正在寻找开发相关的工作，那么在简历上写上“我为 LibreOffice 贡献过代码”将会是您简历的一大亮点。 开发者的任务是改进 LibreOffice 的代码库。首先，庞大的代码库看上去会让人望而生畏。但是，代码的文档质量正在改进，并且您将会得到现有的开发团队的协助。通过本页面的指导，您将能成功提交第一份 patch 补丁。为了让您对代码库有一个大概的概念：

    适合新开发者的贡献步骤

    LibreOffice拥有很大、很复杂的代码库，因此您可能会被吓到，这很正常。LibreOffice的源代码是由许多种编程语言构成的：C, C++、Java、Bash、JavaScript、Python、Perl、SQL、XML等，而且有大约个102,000文件（不含翻译文件）、36,000,000行文本、7,000,000行源代码。

    事实上，没有一个人能够完全了解整个源代码的细节。但是，我们有许多核心开发者，他们每个人均了解代码的其中一部分细节。在这篇指南中，我们将指导您脱离“想要贡献”的状态，成功向LibreOffice贡献第一个补丁、直到该补丁被接受并合并到主代码库。

    沟通渠道

    我们的开发者邮件列表为：libreoffice@lists.freedesktop.org。建议您注册到该邮件列表。您也可以在线跟踪该邮件列表的内容。

    要进行实时沟通，我们使用位于Libera Chat网络的IRC频道：#libreoffice-dev IRC://

    编译LibreOffice

    要进行代码开发，您需要克隆一份源代码到您的本地计算机上。所有的源代码均以git的形式组织，源代码克隆的方式均在针对每个操作系统的“编译指南”页面中进行了说明。

    Windows

    Windows下的开发者需要安装Cygwin以及其它工具。最简单的方式是使用LibreOffice Development Environment (LibreOffice开发环境，LODE)。另请参考Windows下的详细编译指南。

    macOS

    我们建议参照LibreOffice开发环境 (LODE)的指导。有关Xcode的更多信息，请见在macOS上编译LibreOffice。

    Linux

    Linux下的LibreOffice开发环境可以通过您的发行版对应的包管理器进行快速安装。建议您按照“Linux下的编译”页面中的提示进行设置。

    提交补丁的准备工作

    成功编译LibreOffice之后，您就可以提交补丁了。我们使用gerrit来进行代码审核，因此您需要创建一个账户。请参考gerrit setup guide。

    提交补丁基本上有两种方法。如果您熟悉Git Review，那么您可以使用它，但是我们推荐使用另外一个类似的工具： logerrit。

    向类似help等子模块进行代码提交时，您需要注意，您可能仅克隆了该子模块，因此logerrit脚本可能不可用、并且gerrit的钩子可能未安装。子模块的代码提交环境设置，见Development/Submodules。

    找到您要解决的第一个 bug

    恭喜，您已经来到了最有趣的部分。

    解决第一个bug涉及到学习新的工具以及方法，因此我们列出了一些简单的 bug (称为 Easy_Hacks)。我们使用bugzilla来进行bug跟踪，要使用bugzilla您需要创建账户并登录。

    Easy hacks 是真实存在的bug。与其他的bug报告不同，核心开发者已在 easy hacks 中添加了源代码指导或者叙述性的帮助信息，而不是简单地自行修复这些bug，这样就能让其他人来解决该bug。从您感兴趣的编程语言类型 (见上文) 中选择一个bug。在根据编程语言和技能排列的EasyHacks 中，您可以发现有很多可以选择的项目。我们建议您从类别 "Skill level: beginner" 中选择，从而能够把注意力集中在“我如何...”这样的问题上。

    找到了您想要解决的bug之后，请别忘了在bugzilla上将其状态设置为已指派给了您，这样其他人就能知道这个bug已经有人在解决了。如果您正在解决的是那种需要其他人持续参与的bug (比如将foo转换为xyz), 请不要将其设置为已指派给了您，从而能让其他人与您共同解决那个bug。EasyHacks会有人进行监控，如果已指派状态进行了很久却没有任何进展，那么其状态将会被重置为“未指派”。

    当然，还有其他具有挑战性的：

    解决 bug

    Some practical advice, based on experience, which we recommend that you follow is:

    • Never make changes to your copy of master - create a branch instead.
    • Keep a separate branch for each bug, and do not delete the branch until the bug-fix is merged.
    • follow the Code Style (such as variable naming schemes, etc.).
    • If you create new files, please use our License Header.
    • Please avoid larger reformatting of the code for the time being (except for the tasks listed below) - we're pondering auto/magic ways to do that mid- to long-term.
    • Update master before starting on a new bug (and run make check to confirm it compiles cleanly before you make any changes).
    • Do not submit patches that depend on each other, unless being told to do so. Doing so will make your patch incapable of being merged.
    • If your patch is not ready to be merged, assign -2 to it, that way reviewers know it is Work In Progress.
    • Patience is a key, reviewing takes time and we are all volunteers, so expect a couple of days to pass.

    推荐的流程

    1. 更新 master

    Make sure your master is updated and works. If your master is too outdated, you run the risk of not being able to merge your patch.

    As a rule of thumb, use the commands below if:

    • your master is more than a week old.
    • your new bug-fix depends on work that just got merged.

    ./g pull -r
make
make check

    !! make版本必须高于3.8.1。

    Please use the -r switch, which is far more effective than simply pulling. Master is frequently broken, but normally only for a short time (committers normally react fast if they make a wrong commit).

    When make completes you know you have a working master, so if make breaks while compiling your patch it is due to a problem somewhere in your code. make check runs all test cases and ensures you have a working version of LibreOffice. Running plain make before make check does not cost you build time and in the case of test failures, it ensures you have a build that runs.

    2. 在分支上工作

    You might be asked later to make changes to your patch, and if you have created and worked in a separate branch that will be very easy. Please use a new branch (from origin/master) for every bug you work on, once the patch has been merged you can delete the branch. 

    git checkout -b test1 origin/master

    Replace test1 with your preferred name.

    3. 解决该 bug

    Identify the problem, correct the code, generate and test a version. Remember to supply a unit-test whenever possible to verify that the problem is solved.

    There are a number of handy tools to help you

    Do remember to do git commit -a regularly. This gives you the possibility to easily abandon part of your development, should it turn out to be a wrong path.

    4. 提交补丁

    我们建议您将commit信息写成这样： 

       tdf#12345 <short developer description of change, not just the bug title>
   <empty line>
   <description of what the patch does, the more words the better others understand it later>
    • if there is a bugreport related to the commit, it's mandatory to start the first line with a bug reference like tdf#12345 (see details below)
    • use the rest of the first line as a concise summary of your changes. The maximum length for this line is 72 characters.
    • use present tense. tell what the change does. be terse. avoid "decorations" like dashes and brackets that waste space.
    • if you want to provide more text than what fits the 1st line, it's mandatory to leave the 2nd line empty
    • starting from the 3rd line explain what the patch does and why, and if it not obvious also how. These lines should have 80 characters length at most; split into several lines, if your comment is longer. Here you can also describe how the code used to work incorrectly before the change.

    If your patch fixes a bug that is already filed in Bugzilla, then you can take advantage of automatic bug-notifications that are triggered by commit-messages: When the first line of the commit message includes a reference to a bug in the form tdf#12345, then a corresponding comment will automatically be added to the bugreport, when the change is pushed to the repository. See the announcement-thread on mail-archive.com or on fdo-listarchive for more details.

    Verify that your changes don't break automated testing: 

    make check

    Now you can submit the patch to gerrit (see Prepare to submit patches): 

    ./logerrit submit master


    对您提交的补丁进行审阅

    In the case of easy hacks, add the person who provided the code pointers as a reviewer for your patch. You will receive an email whenever there is a change in your patch.

    在审阅过程中，可能出现三种情况：

    • The committer reviewed and tested the patch successfully, then merged it (congratulations)
    • The committer had some comments, which you need to look at
    • Sometimes the patch breaks some other functionality and is marked as “Cannot merge”

    若出现后两种情况，那么您需要更新您的补丁。

    For more on the patch review process, see Development/gerrit/PatchReview.

    更新某个补丁

    检出您需要的分支， 

    git checkout test1

    make the needed changes and test them. It is polite to comment the lines of code you do not want to change or where you do not agree with the committer, this is done directly in gerrit.

    Once you are ready to commit again it is important you use --amend 

    git commit --amend -a

    Important do not use the -m parameter as it will wipe out the gerrit patch id. Let git open an editor, allowing you to edit the commit message (or leave it unchanged). When editing be careful not to remove/modify the last line with the patch id.

    This will ensure you update the patch, instead of generating a new one (with a new Change-Id:).

    将新的补丁集提交到gerrit 

    ./logerrit submit master

    许可证声明

    我们想要将源代码向所有人公开，因此，您需要通过电子邮件发送给我们一封授权声明（请使用 "<您的姓名> license statement" 格式做邮件标题），邮件请发至：libreoffice@lists.freedesktop.org。邮件需要用英文，并需要包含以下内容： 

       All of my past & future contributions to LibreOffice may be
   licensed under the MPLv2/LGPLv3+ dual license.

    It is important to make sure that the mail allows connecting the statement to the contributions, so send the statement from the same email that is used in your commits.

    A slight variation to suit your personal taste is fine as long as the intention is clear. We keep a list of developers in our wiki.

    Please only send the statement no earlier than when you post your first submission to gerrit. If you are underage, ask your parents or legal guardians to send the email (all persons having guardianship).

    If you will be contributing artwork that will be included with the software (such as icons), add this to your license statement email: 

       Additionally, to the extent possible under law, I waive all
   copyright and related or neighboring rights to my past & future
   Artwork and Design contributions to the LibreOffice project, and
   similarly to The Document Foundation, placing such contributions
   under CC0: https://creativecommons.org/publicdomain/zero/1.0

    恭喜

    您已经成功向世界上最受欢迎的开源项目之一贡献了一次修改。

    继续提交补丁，这样的话您很快就会成为一名 committer.

    个人成长路线图

    A developer needs to have specific skills/experience in order to be able to work on LibreOffice Code. This is the path suggested for anyone who wants to get involved in LibreOffice development:

    1. Understand intermediate level C++: Most of the LibreOffice code is in C++, so one should be fluent with C++ in order to be able to work with the code.
    2. Understand git and gerrit: git is the version control software that is used in LibreOffice. One should understand git and gerrit in order to be able to contribute
    3. Be able to build LibreOffice: To be able to change the code, one should be able to build LibreOffice from the sources.
    4. Do at least 10 bug triages: Developers should understand Bugzilla and the workflow associated with bugs and features. This is essential in order to be able to proceed.
    5. Do at least 5 EasyHacks with difficulty beginner (C++): The first step towards being able to understand and change the code.
    6. Do at least 5 EasyHacks with difficulty medium (C++): After doing some easier tasks, it is important to be able to do some more serious work.
    7. Do at least 1 EasyHacks with difficulty interesting
    8. Fix at least 5 regressions: Regressions are usually easy to reproduce, and can be fixed in a reasonable amount of time, so they are suitable for the newcomers
    9. Reach certain number of commits (~60)
    10. Do at least 1 CoreHack


    新手的礼节

    Experienced contributors will help you find solutions to your problems, but there are expectations and limits. Remote mentoring and troubleshooting has a greater cognitive load compared to being physically present. Showing you are well-prepared makes people more motivated to help you.

    General guidelines:

    • When using the chat, immediately describe your problem and stay in the channel for at least an hour.
    • For sharing text with multiple lines in the chat, use a paste service such as the one mentioned in the channel topic.
    • If you have network connection issues, the mailing list works better than the chat.
    • If you are doing a complex multi-step task, it is a good idea to keep personal notes. These will come in handy when you are asked what you did so far.
    • After receiving a reply, acknowledge it somehow. If you disappear without a trace, your helpers will feel distressed.

    If you are facing an issue with git, patch submission or setting up the development environment, it is best to follow these steps:

    1. Try to search for the how-to or solution yourself. Sometimes your helpers have to search as well.
    2. If your search was successful, make an attempt to follow the instructions.
    3. If you did not find any instructions or got stuck applying them, ask for help.

    With these types of issues, helpers are quite happy to try and solve your entire problem for you.

    If you are solving an easy hack, it is good to keep these facts and tips in mind:

    • There is no single document explaining the code base in prose. Educational material is scattered across conference presentation slides, blog posts and wiki pages.
    • The frequency of code comments is less than ideal (you can help!), so you should be prepared to read code.
    • Use git grep, an IDE and OpenGrok to find the definitions of the functions and classes you run into.
    • Investigate the commit history, also for similar topics elsewhere in the code base. OpenGrok's Annotate command can be revealing for this type of detective work.
    • Run a debugger while using LibreOffice to find out what is going on under the hood.
    • Browse the readme files.

    If you ask someone to say how to implement something, you will probably be faced with silence. Easy hacks are supposed to be a learning experience and mentors do not want to ruin it. A proposed implementation will be commented on in the review system.

    Retrieved from "https://wiki.documentfoundation.org/index.php?title=Development/GetInvolved/zh-cn&oldid=743426"