【ceph】开发人员指南--编辑中

原文：CONTRIBUTING TO CEPH: A GUIDE FOR DEVELOPERS¶

注意旧(2016年)开发人员文档已被移动到内部开发人员文档：Internal developer documentation — Ceph Documentation

介绍INTRODUCTION

本指南有两个目的。首先，它应该降低那些希望参与Ceph项目的软件开发人员的门槛。其次，它应该作为Ceph开发者的参考。

我们假设读者已经熟悉了Ceph(分布式对象存储和文件系统，旨在提供卓越的性能，可靠性和可扩展性)。如果没有，请参考项目网站，特别是出版物列表。

由于本文档是供开发人员阅读的，默认他们能上互联网，文中涉及的主题，无论是在Ceph文档中还是在网络上的其他地方，都是通过链接处理的。如果你发现一个链接被破坏了，或者你知道一个更好的链接，请把它作为一个错误报告。

要点ESSENTIALS (TL;DR)

本章介绍了每个Ceph开发人员需要知道的基本信息。

领导LEADS

Ceph项目由Sage Weil领导。此外，每个主要项目组件都有自己的领导者。下表显示了GitHub上的所有领导和昵称：

Scope	Lead	GitHub nick
Ceph	Sage Weil	liewegas
RADOS	Josh Durgin	jdurgin
RGW	Yehuda Sadeh	yehudasa
RBD	Jason Dillaman	dillaman
CephFS	Patrick Donnelly	batrick
Build/Ops	Ken Dreyer	ktdreyer

表中的Ceph特定首字母缩略词在架构  Architecture中解释。

历史HISTORY

看 History chapter of the Wikipedia article.

许可LICENSING

Ceph 是自由软件。
除非另有说明，Ceph 的源代码是在 LGPL2.1 的条款下发布的。完整的细节，见源代码树顶层目录中的文件 COPYING：ceph/COPYING at master · ceph/ceph · GitHub。

源代码仓库SOURCE CODE REPOSITORIES

Ceph的源代码在GitHub上，在Ceph的 "组织 "下面有一些仓库。
要想作为一个开发者对项目做出有意义的贡献，对git的工作知识是必不可少的。
虽然Ceph的 "组织 "包括几个软件仓库，这个文件只包括一个：《GitHub - ceph/ceph: Ceph is a distributed object, block, and file storage platform》https://github.com/ceph/ceph。 

Redmine问题跟踪器REDMINE ISSUE TRACKER

虽然GitHub用于代码，但与Ceph相关的问题(Bug，功能，Backports，文档等)是在http://tracker.ceph.com 跟进，这是由Redmine支持的。

该跟踪器有一个Ceph项目，有一些子项目松散地对应于各种架构组件 (see Architecture).。
仅仅在跟踪器中注册就会自动授予足够的权限来打开新的问题和对现有问题进行评论。
要报告一个错误或提出一个新的功能，跳到Ceph项目(jump to the Ceph project)并点击新问题 New issue.

邮件列表MAILING LIST

Ceph development email discussions take place on the mailing list ceph-devel@vger.kernel.org. The list is open to all. Subscribe by sending a message to majordomo@vger.kernel.org with the line:

subscribe ceph-devel
 

in the body of the message.

There are also ceph/COPYING at master · ceph/ceph · GitHub.

IRC

In addition to mailing lists, the Ceph community also communicates in real time using Internet Relay Chat.

See https://ceph.com/irc/ for how to set up your IRC client and a list of channels.

SUBMITTING PATCHES

The canonical instructions for submitting patches are contained in the file CONTRIBUTING.rst in the top-level directory of the source-code tree. There may be some overlap between this guide and that file.

All newcomers are encouraged to read that file carefully.

BUILDING FROM SOURCE

See instructions at Build Ceph.

USING CCACHE TO SPEED UP LOCAL BUILDS

Rebuilds of the ceph source tree can benefit significantly from use of ccache. Many a times while switching branches and such, one might see build failures for certain older branches mostly due to older build artifacts. These rebuilds can significantly benefit the use of ccache. For a full clean source tree, one could do

$ make clean

# note the following will nuke everything in the source tree that
# isn't tracked by git, so make sure to backup any log files /conf options

$ git clean -fdx; git submodule foreach git clean -fdx
 

ccache is available as a package in most distros. To build ceph with ccache one can:

$ cmake -DWITH_CCACHE=ON ..
 

ccache can also be used for speeding up all builds in the system. for more details refer to the run modes of the ccache manual. The default settings of ccache can be displayed with ccache -s.

DEVELOPMENT-MODE CLUSTER

See Developer Guide (Quick).

BACKPORTING

All bugfixes should be merged to the master branch before being backported. To flag a bugfix for backporting, make sure it has a tracker issue associated with it and set the Backport field to a comma-separated list of previous releases (e.g. “hammer,jewel”) that you think need the backport. The rest (including the actual backporting) will be taken care of by the Stable Releases and Backports team.

GUIDANCE FOR USE OF CLUSTER LOG

If your patches emit messages to the Ceph cluster log, please consult this guidance: Use of the cluster log.

WHAT IS MERGED WHERE AND WHEN ?

Commits are merged into branches according to criteria that change during the lifecycle of a Ceph release. This chapter is the inventory of what can be merged in which branch at a given point in time.

DEVELOPMENT RELEASES (I.E. X.0.Z)

WHAT ?

• features

• bug fixes

WHERE ?

Features are merged to the master branch. Bug fixes should be merged to the corresponding named branch (e.g. “jewel” for 10.0.z, “kraken” for 11.0.z, etc.). However, this is not mandatory - bug fixes can be merged to the master branch as well, since the master branch is periodically merged to the named branch during the development releases phase. In either case, if the bugfix is important it can also be flagged for backport to one or more previous stable releases.

WHEN ?

After the stable release candidates of the previous release enters phase 2 (see below). For example: the “jewel” named branch was created when the infernalis release candidates entered phase 2. From this point on, master was no longer associated with infernalis. As soon as the named branch of the next stable release is created, master starts getting periodically merged into it.

BRANCH MERGES

• The branch of the stable release is merged periodically into master.

• The master branch is merged periodically into the branch of the stable release.

• The master is merged into the branch of the stable release immediately after each development x.0.z release.

STABLE RELEASE CANDIDATES (I.E. X.1.Z) PHASE 1

WHAT ?

• bug fixes only

WHERE ?

The branch of the stable release (e.g. “jewel” for 10.0.z, “kraken” for 11.0.z, etc.) or master. Bug fixes should be merged to the named branch corresponding to the stable release candidate (e.g. “jewel” for 10.1.z) or to master. During this phase, all commits to master will be merged to the named branch, and vice versa. In other words, it makes no difference whether a commit is merged to the named branch or to master - it will make it into the next release candidate either way.

WHEN ?

After the first stable release candidate is published, i.e. after the x.1.0 tag is set in the release branch.

BRANCH MERGES

• The branch of the stable release is merged periodically into master.

• The master branch is merged periodically into the branch of the stable release.

• The master is merged into the branch of the stable release immediately after each x.1.z release candidate.

STABLE RELEASE CANDIDATES (I.E. X.1.Z) PHASE 2

WHAT ?

• bug fixes only

WHERE ?

The branch of the stable release (e.g. “jewel” for 10.0.z, “kraken” for 11.0.z, etc.). During this phase, all commits to the named branch will be merged into master. Cherry-picking to the named branch during release candidate phase 2 is done manually since the official backporting process only begins when the release is pronounced “stable”.

WHEN ?

After Sage Weil decides it is time for phase 2 to happen.

BRANCH MERGES

• The branch of the stable release is merged periodically into master.

STABLE RELEASES (I.E. X.2.Z)

WHAT ?

• bug fixes

• features are sometime accepted

• commits should be cherry-picked from master when possible

• commits that are not cherry-picked from master must be about a bug unique to the stable release

• see also the backport HOWTO

WHERE ?

The branch of the stable release (hammer for 0.94.x, infernalis for 9.2.x, etc.)

WHEN ?

After the stable release is published, i.e. after the “vx.2.0” tag is set in the release branch.

BRANCH MERGES

Never

ISSUE TRACKER

See Redmine issue tracker for a brief introduction to the Ceph Issue Tracker.

Ceph developers use the issue tracker to

1. keep track of issues - bugs, fix requests, feature requests, backport requests, etc.

2. communicate with other developers and keep them informed as work on the issues progresses.

ISSUE TRACKER CONVENTIONS

When you start working on an existing issue, it’s nice to let the other developers know this - to avoid duplication of labor. Typically, this is done by changing the Assignee field (to yourself) and changing the Status to In progress. Newcomers to the Ceph community typically do not have sufficient privileges to update these fields, however: they can simply update the issue with a brief note.

Meanings of some commonly used statuses

Status	Me