Gentoo开发者手册

内容:

• 介绍
  这部分介绍了应用于Gentoo开发的大部分领域的规则。这部分只对Gentoo开发者有用；如果你不是，你可以掠过这部分。
  1. 介绍
     本节概述了Gentoo开发者手册的目的。
  2. 成为一个开发者
     本节解释了怎样成为一个Gentoo开发者。
  3. 你能得到什么
     本节简述了提供给Gentoo开发者的服务。
  4. 为新开发者提供的帮助
     本节给新开发者提供了帮助和指令。
  5. 开发者等级
     本节简要介绍了Gentoo开发者等级和管理结构。
  6. 工作人员策略
     本节介绍了Gentoo工作人员的招募和退休策略。
• 指南
  本部分解释了各种开发流程并为Gentoo开发者提供了开发标准。
  1. Ebuild HOWTO
     本节描述了Gentoo Linux Portage系统，怎样为Gentoo创建新的软件包，某种程度上本节应被视为Gentoo开发者的开发标准。本节仍在开发中，内容仍然在不断的变化和更新。本节并没有包含所有的有关开发的内容。你应该将本节和portage提供的手册页（特别是ebuild(5)）和Gentoo Linux开发策略配合使用。
  2. Eclass HOWTO
     本节的目的在于给开发者提供一个详细的讲解eclass的作用和它们应用于ebuild的指南。
  3. 常见ebuild错误
     本节解释了贡献者和开发者在ebuild编写和提交过程中常犯的错误。
  4. Gentoo Metadata
     本节解释了Portage树里使用的metadata.xml的由来和作用。
  5. Ebuild维护HOWTO
     本节描述了开发者在维护portage树里的ebuild时怎样完成通常的工作。
  6. Manifest签署指南
     本节描述了开发者怎样使用GPG签署Portage树里的Manifest文件。
• 规则
  这部分包括了我们期望开发者在向CVS检入文件的时候所应遵守的各种规则。　
  1. Ebuild规则
     本节概述了Portage里的每一个ebuild应该遵守的ebuild规则。
  2. 礼节规则
     本节概述了每个Gentoo开发者应该遵守的礼节。

A. 介绍

1. 介绍

1.a. 介绍

这本手册的目的是扼要的说明Gentoo的开发规则，并且使作为开发者的您，了解我们认为是我们开发系统的核心价值的规则、标准和过程。

这本手册并不是一本面面俱到的指导书——你在开发中可能遇到的问题是不能穷举的。因而，这本手册旨在教你一些基本的原则，而我们认为这些原则能让你成为一个好的Gentoo开发者——所谓师傅领进门，剩下的修行就要靠你自身了！

如果你刚刚接触Gentoo开发，或者你是个老手，但对于某些问题不确定，你可以在gentoo-dev邮件列表或#gentoo-dev上提问。

1.b. 要求

在你开始尝试之前，你应该拥有一个可以工作的Gentoo系统。这无论对于文档还是开发来说都是很重要的。而且我们也建议你熟悉用户手册中“用Gentoo工作”那一节所提到的主题，这对于你的开发工作有帮助。

这本手册的大部分内容是针对开发者的，但如果你只是对Gentoo如何进行开发工作感兴趣，这本手册也会提供同样具有价值的内容。

想让自己被注意到（并且有可能成为一名Gentoo开发者！）的最好方法就是在Gentoo Bugzilla上提交准确的bug报告（如果可能的话，附上补丁），并帮助我们提出你认为如何能让Gentoo变得更好的意见，比如提交可以增加新特性的补丁，提交新的ebuild，或者解决现有的问题。

2. 成为一个开发者

2.a. 介绍

本节要讨论的话题是成为一名Gentoo开发者的多种途径。在他们成为正式的开发者之前，"新成员"不得不经历各种不同的挑战。

2.b. 帮助

首先；要成为一名开发者，你要么申请一个空缺的职位；要么以给用户提供技术支持或者提交bug报告的形式来提供帮助——我们会注意到那些经常给Gentoo作贡献的贡献者，并且奖励他们，给他们以成为Gentoo开发者的机会。为Gentoo做贡献很多种途径，Gentoo开发者事务组招募团队不只是在寻找开发者——为了让我们的发行版顺利地运作，文档编写者和基础架构维护者也同样重要。

你应该在Gentoo月报中寻找给予开发者的空缺职位，或者在irc.freenode.net的#gentoo-bugs频道中利用/topic来寻找空缺的职位——如果你认为你可以胜任其中之一的职位，试着找一个愿意担保你的导师，或者联系Gentoo招募者，他们有可能会帮你找一个导师。请不要自己提交"新开发者"bug，因为这件事是由导师负责完成的，而且任何这样的bug都将会被关闭。

2.c. 指导

新的开发者都必须有一个导师，这个导师应该是当前的Gentoo开发者，他将负责指导这个新的开发者，并在这个开发者通过招募过程之后继续提供帮助。

导师将帮助解答你的问题，还会扼要地介绍你的Gentoo职责，特别是和你刚开始工作有关的那些职责。

只要一个开发者同意指导一个新的开发者，这个导师就应该提交一个bug，并将它委派给Gentoo招募者——Gentoo招募者页面详细地解释了应该提交哪些信息。

2.d. 等待

所有新的开发者都要进入最长一个月的等待期，等待的时间取决于导师认为这个开发者是否已经准备好了，和从其他相关事情上所获得的反馈。在这段时间内，新的开发者应该完成由导师和Gentoo招募者审查的测验，以确保这个开发者"准备好了"。在特殊的情况下，这个等待的时间由Gentoo招募者和／或Gentoo开发者事务组决定。

测验分两种：ebuild测验和staff测验。那些只想工作在基础架构，GLSA或者其他非ebuild部分的开发者应该参加staff测验；任何想对Portage树有commit权限的开发者则应该参加ebuild测验。

一旦新的开发者完成了测验，这个开发者应该将它发送给负责审查的导师和Gentoo招募者。如果这个测验的回答足够好，那么这个招募过程将继续下去。否则，新的开发者可以选择重新做这个测验，但要在等待期内完成。

另外，新的开发者应该积极地回答招募团队中的人员所提出的任何问题——任何不及时回答的开发者，他们的"新开发者"bug将会被关闭，而这个bug只有在Gentoo招募者慎重考虑之后才会重新开启。

2.e. 跨越障碍

在你的导师和Gentoo招募者审核了你的测验，并且认为你达到一定的水平之后，你应该把测验发送给Gentoo招募者，同时附上你的SSH2的DSA公钥（比如，id_dsa.pub）。如果招募团队认为你的测验是令人满意的，他们将建立你所要求的那些服务。

在这之后，你将进入一个为期30天的"试用期"，在这段时间内，你的导师会对你的行为负责，并且提供相应的报告——同样在这段时间内，Gentoo招募者可能会拒绝这个新的开发者，如果他们认为这样做合适的话。

3. 你能得到什么

3.a. 介绍

Gentoo给开发者提供所有必要的服务，只要他们认为对他们的开发有帮助。如果你有一些其他的需求，请不要犹豫，可以联系基础架构团队。

一旦你成为一位被授权的开发者，你的招募者就应该为你提供下面的服务。如果你遇到任何问题，请询问你的招募者或对于该服务有管理权限的人员。

3.b. Bugzilla

开发者有权力修改Bugzilla上所有的bug。如果你已经有了一个帐号，请联系Bugzilla的管理者让他把你原来的邮箱地址改成你的Gentoo邮箱地址。

3.c. CVS

并不是所有的开发者都拥有CVS权限——如果你需要gentoo，gentoo-projects，或者gentoo-x86树的Portage权限，联系招募团队中的成员，让他帮你做这件事情。当然，你可能需要设法证明你的这种需求是必要和正确的。

3.d. IRC

当你是开发者的时候，在#gentoo-dev上你会有管理员状态来表明你是一位开发者。如果你没有，请联系开发者事务组。另外，团队的领导者可能决定在特殊的频道上给你管理员状态，比如#gentoo-hardened。在#gentoo-dev上管理员权力的滥用可能会导致你的管理员权力马上被取消，也有可能取消你的开发者权力。如果你被赋予了管理员权力，我们希望你建设性地使用它来让每个人都受益，特别是当开发者或者用户在频道上捣乱的时候。

#gentoo上的管理员状态由开发者事务组来发放；拥有管理员状态并不能说明他就是一位开发者。

"特殊的"Gentoo频道，比如#gentoo-hardened和#gentoo-server，由团队来决定开放给哪些人——在这里，分别是hardened团队和server团队。

IRC频道属于相关项目的领导者所有，不管是出于策略或是管理的目的，所有者拥有赋予或取消某成员发言的权力。如果你认为这些权力被滥用了，或者被不怀好意地使用了；请告知Gentoo开发者事务组。

3.e. 论坛［可选］

如果需要，可以向#gentoo-forums或者forum-mods@gentoo.org的论坛管理者要求更新你在Gentoo论坛上的状态。论坛的帐号不是必需的。

3.f. 邮箱

每个开发者都将拥有一个专为Gentoo使用的邮箱地址，邮箱地址格式为developer@gentoo.org。

更详细的介绍，请查看http://www.gentoo.org/proj/en/infrastructure/dev-email.xml

3.g. 邮件列表

每个开发者都必须订阅gentoo-core邮件列表和gentoo-dev-announce邮件列表。每个开发者都应该订阅gentoo-dev邮件列表和gentoo-project邮件列表，尽管这两个列表的订阅不是必须的。如果你有任何困难或想订阅以上提到的邮件列表，请联系招募团队。

gentoo-core邮件列表被用做内部讨论；技术讨论应该发在gentoo-dev邮件列表之上；和主题无关的讨论以及非技术讨论应该在gentoo-project邮件列表上进行；gentoo-dev-announce邮件列表仅仅是为了发布通告。如果你给dev-announce邮件列表发送了一个邮件并期待有相关的讨论发生，你应该手动地将该邮件发送到另外一个相关的邮件列表之上，并适当地设置你邮件的回复字段。

如果你已经用其他邮箱地址订阅了Gentoo邮件列表，你应该退订并用你新的邮箱地址来重新订阅该邮件列表。

3.h. shell访问

这时，开发者在dev.gentoo.org上将拥有一个shell帐号——这个帐号提供邮件存储，SMTP转发和为开发者使用的通向freenode的IRC通道。

为了保证安全，访问只能通过SSH密钥，你的导师应该把SSH密钥放在你的帐号上并允许你登录：更多关于SSH密钥的细节，请查看http://www.gentoo.org/proj/en/infrastructure/cvs-sshkeys.xml。

3.i. 服务使用政策

Gentoo所提供的服务应该仅被用来做开发之用。基础架构团队拥有关闭可能具有安全危害帐号的权力，这包括不经常活动的帐号会被基础架构团队冻结，并且你在#gentoo-dev频道上的状态也会被通知。

如果在你帐号上的文件被认为对其他开发者或其他使用者有害，或者对于Gentoo项目存在危害（比如非法的.torrent文件），Gentoo基础架构团队将冻结你的帐号，只有在Gentoo开发者事务组调查之后才能解冻你的帐号。在很多情况下，如果发现有这样的文件存在，你的开发者权力也会被冻结。同样的政策也适用于Gentoo CVS和其他Gentoo所提供的服务。

3.j. 活动政策

生活瞬息万变，Gentoo可以理解你并不是每时每刻都有空。如果你知道你将在一段时间内没有空（比如假期，工作中的大项目，家庭需要，等等），我们恳请你利用devaway系统来通知大家你要暂离一段时间。

在dev.gentoo.org上
$ echo "Away until 2007-08-30, contact $dev1 in my absence" > ~/.away

在dev.gentoo.org上
$ rm ~/.away

为了随时更新开发者的数量，同时也为了保持我们资源的安全性，开发者事务组周期性地调查开发者的活跃度，试图找出懒散的开发者。如果一个开发者超过60天没有做贡献，那么他就被认为是不活跃的。活跃度由CVS的commit，bugzilla统计数据和同伴的反馈来决定。并不是每位开发者的活跃度都是这么容易追踪的。开发者事务组经常需要从疑似不活跃的开发者所在项目的领导者或者团队成员来获取反馈。

如果一个开发者有超过60天不活跃的记录，那么他可能会被劝退。开发者事务组将首先调查评估当前的情况，并试图联系这位开发者。如果联系不上，招募团队会选择让这位开发者退职。请注意：如果你使用devway系统超过了60天，你也会被认为是不活跃。当然，回归的日期将被酌情考虑。如果由于你的懒散不活跃而导致了你的退职，并希望重新回来，你只需要联系招募团队并重新开始招募过程。

4. 为新开发者提供的帮助

4.a. 使用CVS

介绍

这不是一本讲解如何使用CVS的手册。如果你需要了解如何使用CVS，请查看CVS的info或者/doc/zh_cn/cvs-tutorial.xml。相反地，这本手册特别关注如何在Gentoo的ebuild树中使用CVS和Repoman。

配置

一般来说，你会希望在~/.cvsrc中加入下面的几句话。

cvs -q -z0
diff -u -B
checkout -P
update -d -P

最后，很多使用CVS的人喜欢使用压缩选项（-z#）。我们要求那些不通过拨号连接的开发者使用选项-z0（考虑到我们CVS仓库的内容和我们CVS服务器的负载），在没有压缩的情况下，实际上你会感受到速度的提升。

从CVS/SVN中checkout

在Gentoo的CVS仓库中有一些很有用的模块。Ebuild被存放在gentoo-x86模块中。gentoo包含了网站，文档，开发者目录，开发者图片等的XML文件。gentoo-projects包含了各种各样的项目，并替换了gentoo-srccvs模块。gentoo-src被保留，成为了历史。如果你仍然在使用它，请转移到一个不同的cvs模块。

# cvs -d username@cvs.gentoo.org:/var/cvsroot co gentoo-x86

在任何时候，在树中工作之前，总是记得要先更新，用来检查仓库中的内容是否有改变，以防止冲突的发生。如果你不希望等待整棵树的更新，你可以在任何一个子目录中进行更新，但不时地更新你的整棵树是个很好的主意。

# cd gentoo-x86
# cvs update

Gentoo也为那些偏爱SVN的人提供了subversion服务。许多核心项目，比如portage和baselayout现在也架设在这里。

# svn co svn+ssh://username@cvs.gentoo.org/var/svnroot/portage

更新Portage

如果你想使用CVS作为你主要的Portage树，那么你可以在/etc/make.conf中加入下面的几行，用你的名字替换其中的you。

SYNC="cvs://you@cvs.gentoo.org:/var/cvsroot"
CVSROOT=":ext:you@cvs.gentoo.org:/var/cvsroot"

在支持的架构上，你应该总是在你的FEATURES中加入sandbox来保证ebuild不会直接修改根文件系统。

增加／删除包

假设你准备在app-misc中加入一个全新的包foo：

（用你checkout出来的CVS树的位置来替换CVSROOT。）
# cd $CVSROOT/app-misc
（在CVS树中工作之前总是要先更新！）
# cvs update
# mkdir foo
（这里，我们将foo包目录加入了CVS仓库。）
# cvs add foo
# cd foo
（最好将你正在进行中的ebuild放置在CVS树之外的overlay中。）
# cp /path/to/foo-1.0.ebuild ./
（当建立manifest的时候，确保PORTDIR_OVERLAY设置成CVS目录。）
# ebuild foo-1.0.ebuild digest
# ${EDITOR} metadata.xml
你不一定再需要files目录了。
# cvs add foo-1.0.ebuild metadata.xml files
（不要忘记创建ChangeLog文件——查看echangelog的man帮助。）
# echangelog "New ebuild for foo. Ebuild written by me. Fixes bug #XXXXXX."

查看Gentoo Metadata章节以获得更多的信息。

在这个时刻，你已经准备好commit了（查看下面的Commits章节）。但如果当foo-1.1发布的时候你想要删除foo-1.0，该怎么办呢？

# cd CVSROOT/app-misc/foo
# cvs update
# cvs remove -f foo-1.0.ebuild

现在你已经准备好可以commit了。（查看下面的Commits章节）

Commits

请一直使用repoman commit，而不是cvs commit。Repoman是一个质量保障（QA）工具，它会执行基本的检查并且建立Manifests。如果你对repoman输出的某些部分不清楚，请查看man repoman。另外，你可能会对不断地输入密码而感到厌倦；keychain（http://www.gentoo.org/proj/zh_cn/keychain.xml）可以帮助你。

（在运行repoman之前，请确保没有root用户所拥有的文件！）
（"scan"扫描当前的目录来查看QA事务。"full"选项更加完整。）
# repoman scan
（"commit"先做scan，然后commit，同时更新Manifest。确认你已经
加入了冗长而有用的CVS ChangeLog信息……）
# repoman commit

提升CVS的速度

如果你到cvs服务器有很高的ping时间，你可能会希望使用ssh主从设置（你只需要连接到其他的ssh服务器一次，然后通过这个连接来执行后面的命令）。这样，你省下了握手的时间，可以整体提高3倍的checkout/commit速度。只需要将下面的代码加入到你的设置中即可。

Host *
  ControlMaster auto
  ControlPath ~/.ssh/master-%r@%h:%p

在这样做了之后，你可以用这个命令启动一个后台的主连接

你可以在ssh的man手册中找到下面参数的含义
$ ssh -M -N -f ${USER}@cvs.gentoo.org

4.b. 其他事项

在镜像上放置文件

Gentoo镜像系统可自动获取Distfiles。你只需要监视你的distfiles是否有读取错误。请查看Distfiles概览以获得详细的指令。

邮件和网页

我们的基础架构允许开发者管理他们自己的邮件。http://www.gentoo.org/proj/en/infrastructure/dev-email.xml包含了如何配置你的@gentoo.org邮件的指令。

开发者拥有发布网页的权力，http://dev.gentoo.org/~$YOURNAME。请查看网页空间配置指南以获得更多详细的信息。

Planet Gentoo"博客"

我们有一项服务，Planet Gentoo。这项服务汇集由做贡献的开发者所写的文章。这项服务是可选的，但是我们鼓励你加入。这可以促进开发者之间的交流，而且用户也会觉得很有趣，值得一读。

为了能够在Planet Gentoo上发布内容，你需要有一个你自己的博客。许多网站提供这种免费的服务，或者你可以自己架设一个博客（如果你有这个资源的话）。作为另外一种选择，我们可以为你建立一个博客。

我们希望保持Planet Gentoo的内容是与Gentoo相关的，或者是Gentoo相关的开发和事件。

如果我们为你建立了博客，你的博客内容应当是主题相关的（关于Gentoo相关的文章）。你也需要了解，如果你失去了你的开发者状态，你将不能够在你的博客上编辑文章。

如果你在其他地方有一个博客，那么你需要提供一份XML的内容feed。如果你的博客是分类别的，我们需要一份关于"Gentoo"类别的XML feed，而不是其他部分。这也许不是一个问题，因为几乎所有的博客都提供像这样的标准feed服务。

尽管这是常识，但是请注意你所写的内容。你的观点可能会被不恰当地理解为这是Gentoo的观点。请注意不要破坏我们的形象。

如果你有兴趣对Planet Gentoo做贡献，请发邮件到user-relations@gentoo.org。你可以请求一个建立在Gentoo空间上的博客，或者给出你现有博客的详细信息。我们会处理好这些细节，并让你的博客正确地运行起来。

5. 开发者等级

5.a. 介绍

本节旨在分析Gentoo的开发架构并且帮助开发者了解Gentoo Linux开发管理是如何构成的。

5.b. Gentoo管理结构的历史简介

第一次尝试来建立一个管理结构以解决合作和交流问题发生在2003年，GLEP 4中描述了当时提议的管理结构。当Gentoo不断地壮大，我们发现了这个管理结构的一些问题，并且我们需要新的一个结构来解决这些问题。GLEP 39描述了在这背后的原因和这次讨论的结果。

5.c. 按照GLEP 39建立的当前的管理结构

所谓项目就是为了一个目的（或一些目的）而一同工作的一群开发者。

• 只要一个项目存在，那么在www.gentoo.org/proj/en/<project name>上就会有相应的网页被维护（"维护"意味着页面上的信息是正确的，并且没有过期）。如果网页没有被维护，那么就可以认为这个项目已经死了。
• 一个项目可能有一个或多个领导者。领导者由这个项目的成员推选出来。每12个月必须至少选举一次，选举可以随时举行。
• 一个项目可能没有或者有多个子项目。子项目是提供一些附加结构的项目，它们的网页也放置在主项目的空间上。
• 并不是每件事（或每个人）都需要有一个项目。
• 项目没有必要一定是长期的。
• 一个项目可能与其他的项目发生冲突。这也没有关系。
• 任何开发者都可以建立一个项目，只需要在gentoo/xml/htdocs/proj/en下建立一个新的页面（更准确地说是目录和网页），并且在gentoo-dev-announce邮件列表上通告一下就可以了。

全局的事务由选举出来的Gentoo议会来决定。

• 议会成员的数量是固定的。（在第一次的选举中，经大家口头表决通过，这个数字被确定为7个人。）
• 议会成员每年都由全体开发者选举产生。
• 议会至少每个月必须召开一次公开会议。
• 议会的决定由参加者（或者他们的代理人）投票决定，采取少数服从多数的原则。
• 如果一个议会成员（或者他们指定的代理人）连续两次没有参加会议，他们便被标识为偷懒者（slacker）。
• 如果一个已经被标识为偷懒者的议会成员错过了另外一次会议（或者他们指定的代理人也没有出现），那么他们将失去这个职位，同时将举行一个新的选举以接替这个人。这个新产生的议会成员的任期会缩短，因为一年一度的选举还会重新选举出新的成员。
• 由于以前过渡的偷懒而被踢出去的议会成员可以竞争以后的选举，包括寻找他们的接班人的那次选举。当然，他们应该为他们偷懒的原因进行辩解，并且应当知道如果他们自己不辩解的话也会被人指出来。
• 当一个成员被选举出来的时候，这个偷懒者的标志会被去除。
• 如果任何一个会议有少于一半的议会成员参加，那么一个新的选举必须在一个月之内举行。年度的选举时间便从这个时候开始计算。
• 如果你对惩戒措施感到不满，你可以向议会上诉。
• 一位代理人一定不能是现在的议会成员，而且在一个会议中，任何一个人不能担当多于一个人的代理人。

5.d. Gentoo管理结构的影响

采用了新管理结构的结果是全局事务由选举出来的议会决定。这给了Gentoo一个大概的方向——只影响一两个项目的小事务应该在所涉及的项目组内决定，也许还可以听取其他开发者的意见。议会应当成为开发者群体的一个公正的代表，因为每一个开发者都能够投票，所以利益应该以一种公平的方式来表现。如果议会做得很糟糕，而且大多数开发者对他们的工作不满意，这个议会可以被投票免去。

一个项目内部的决定由在项目内的人员自行决定，当然不同项目之间的合作是必要的。（子）项目的领导者通常对此负责。

大多数的项目都有一个运作和策略领导者（Operational and Strategic lead），但是基本上应当由项目来决定哪些职位该被创建并且是如何称呼的——这条规则同样适用于子项目。

一些项目指定了一位联系人用来和其他项目进行交流，比如：在论坛项目中的一位开发者负责与基础架构项目的沟通。

从各方面来说，当前的管理结构没有明确表明项目领导者的职责明细。项目领导者由项目的成员选出来，通常的职责是满足“任何成员所需”，如果这项职责没有完成，成员可以选举出一个新的领导者（如果他们可以找到一位接替者！）

6. 工作人员策略

B. 指南

1. Ebuild HOWTO

2. Eclass HOWTO

3. 常见ebuild错误

4. Gentoo Metadata

5. Ebuild维护HOWTO

6. Manifest签署指南

C. 规则

1. Ebuild规则

2. 礼节规则

本文档的内容遵循知识共享-署名-相同方式共享许可协议