4 This chapter presents essential information that every Ceph developer needs
10 The Ceph project is led by Sage Weil. In addition, each major project
11 component has its own lead. The following table shows all the leads and
12 their nicks on `GitHub`_:
14 .. _github: https://github.com/
16 ========= ================ =============
17 Scope Lead GitHub nick
18 ========= ================ =============
19 Ceph Sage Weil liewegas
20 RADOS Neha Ojha neha-ojha
21 RGW Yehuda Sadeh yehudasa
22 RGW Matt Benjamin mattbenjamin
24 CephFS Patrick Donnelly batrick
25 Dashboard Ernesto Puerta epuertat
27 Build/Ops Ken Dreyer ktdreyer
28 Docs Zac Dover zdover23
29 ========= ================ =============
31 The Ceph-specific acronyms in the table are explained in
37 See the `History chapter of the Wikipedia article`_.
39 .. _`History chapter of the Wikipedia article`: https://en.wikipedia.org/wiki/Ceph_%28software%29#History
44 Ceph is free software.
46 Unless stated otherwise, the Ceph source code is distributed under the
47 terms of the LGPL2.1 or LGPL3.0. For full details, see the file
48 `COPYING`_ in the top-level directory of the source-code tree.
51 https://github.com/ceph/ceph/blob/master/COPYING
53 Source code repositories
54 ------------------------
56 The source code of Ceph lives on `GitHub`_ in a number of repositories below
57 the `Ceph "organization"`_.
59 .. _`Ceph "organization"`: https://github.com/ceph
61 A working knowledge of git_ is essential to make a meaningful contribution to the project as a developer.
63 .. _git: https://git-scm.com/doc
65 Although the `Ceph "organization"`_ includes several software repositories,
66 this document covers only one: https://github.com/ceph/ceph.
71 Although `GitHub`_ is used for code, Ceph-related issues (Bugs, Features,
72 Backports, Documentation, etc.) are tracked at http://tracker.ceph.com,
73 which is powered by `Redmine`_.
75 .. _Redmine: http://www.redmine.org
77 The tracker has a Ceph project with a number of subprojects loosely
78 corresponding to the various architectural components (see
79 :doc:`/architecture`).
81 Mere `registration`_ in the tracker automatically grants permissions
82 sufficient to open new issues and comment on existing ones.
84 .. _registration: http://tracker.ceph.com/account/register
86 To report a bug or propose a new feature, `jump to the Ceph project`_ and
87 click on `New issue`_.
89 .. _`jump to the Ceph project`: http://tracker.ceph.com/projects/ceph
90 .. _`New issue`: http://tracker.ceph.com/projects/ceph/issues/new
97 Ceph Development Mailing List
98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99 The ``dev@ceph.io`` list is for discussion about the development of Ceph,
100 its interoperability with other technology, and the operations of the
103 The email discussion list for Ceph development is open to all. Subscribe by
104 sending a message to ``dev-request@ceph.io`` with the following line in the
105 body of the message::
110 Ceph Client Patch Review Mailing List
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112 The ``ceph-devel@vger.kernel.org`` list is for discussion and patch review
113 for the Linux kernel Ceph client component. Note that this list used to
114 be an all-encompassing list for developers. When searching the archives,
115 remember that this list contains the generic devel-ceph archives before mid-2018.
117 Subscribe to the list covering the Linux kernel Ceph client component by sending
118 a message to ``majordomo@vger.kernel.org`` with the following line in the body
124 Other Ceph Mailing Lists
125 ~~~~~~~~~~~~~~~~~~~~~~~~
127 There are also `other Ceph-related mailing lists`_.
129 .. _`other Ceph-related mailing lists`: https://ceph.com/irc/
137 In addition to mailing lists, the Ceph community also communicates in real time
138 using `Internet Relay Chat`_.
140 .. _`Internet Relay Chat`: http://www.irchelp.org/
142 The Ceph community gathers in the #ceph channel of the Open and Free Technology
143 Community (OFTC) IRC network.
145 Created in 1988, Internet Relay Chat (IRC) is a relay-based, real-time chat
146 protocol. It is mainly designed for group (many-to-many) communication in
147 discussion forums called channels, but also allows one-to-one communication via
148 private message. On IRC you can talk to many other members using Ceph, on
149 topics ranging from idle chit-chat to support questions. Though a channel might
150 have many people in it at any one time, they might not always be at their
151 keyboard; so if no-one responds, just wait around and someone will hopefully
157 If you intend to use the IRC service on a continued basis, you are advised to
158 register an account. Registering gives you a unique IRC identity and allows you
159 to access channels where unregistered users have been locked out for technical
162 See ``the official OFTC (Open and Free Technology Community) documentation's
163 registration instructions
164 <https://www.oftc.net/Services/#register-your-account>`` to learn how to
165 register your IRC account.
170 To connect to the OFTC IRC network, download an IRC client and configure it to
171 connect to ``irc.oftc.net``. Then join one or more of the channels. Discussions
172 inside #ceph are logged and archives are available online.
174 Here are the real-time discussion channels for the Ceph community:
180 - #ceph-orchestrators
184 .. _submitting-patches:
189 The canonical instructions for submitting patches are contained in the
190 file `CONTRIBUTING.rst`_ in the top-level directory of the source-code
191 tree. There may be some overlap between this guide and that file.
193 .. _`CONTRIBUTING.rst`:
194 https://github.com/ceph/ceph/blob/main/CONTRIBUTING.rst
196 All newcomers are encouraged to read that file carefully.
201 See instructions at :doc:`/install/build-ceph`.
203 Using ccache to speed up local builds
204 -------------------------------------
205 `ccache`_ can make the process of rebuilding the ceph source tree faster.
207 Before you use `ccache`_ to speed up your rebuilds of the ceph source tree,
208 make sure that your source tree is clean and will produce no build failures.
209 When you have a clean source tree, you can confidently use `ccache`_, secure in
210 the knowledge that you're not using a dirty tree.
212 Old build artifacts can cause build failures. You might introduce these
213 artifacts unknowingly when switching from one branch to another. If you see
214 build errors when you attempt a local build, follow the procedure below to
215 clean your source tree.
217 Cleaning the Source Tree
218 ~~~~~~~~~~~~~~~~~~~~~~~~
224 .. note:: The following commands will remove everything in the source tree
225 that isn't tracked by git. Make sure to back up your log files
226 and configuration options before running these commands.
230 git clean -fdx; git submodule foreach git clean -fdx
232 Building Ceph with ccache
233 ~~~~~~~~~~~~~~~~~~~~~~~~~
235 ``ccache`` is available as a package in most distros. To build ceph with
236 ccache, run the following command.
240 cmake -DWITH_CCACHE=ON ..
242 Using ccache to Speed Up Build Times
243 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
245 ``ccache`` can be used for speeding up all builds of the system. For more
246 details, refer to the `run modes`_ section of the ccache manual. The default
247 settings of ``ccache`` can be displayed with the ``ccache -s`` command.
249 .. note:: We recommend overriding the ``max_size``. The default is 10G.
250 Use a larger value, like 25G. Refer to the `configuration`_ section
251 of the ccache manual for more information.
253 To further increase the cache hit rate and reduce compile times in a
254 development environment, set the version information and build timestamps to
255 fixed values. This makes it unnecessary to rebuild the binaries that contain
258 This can be achieved by adding the following settings to the ``ccache``
259 configuration file ``ccache.conf``::
261 sloppiness = time_macros
262 run_second_cpp = true
264 Now, set the environment variable ``SOURCE_DATE_EPOCH`` to a fixed value (a
265 UNIX timestamp) and set ``ENABLE_GIT_VERSION`` to ``OFF`` when running
270 export SOURCE_DATE_EPOCH=946684800
271 cmake -DWITH_CCACHE=ON -DENABLE_GIT_VERSION=OFF ..
273 .. note:: Binaries produced with these build options are not suitable for
274 production or debugging purposes, as they do not contain the correct build
275 time and git version information.
277 .. _`ccache`: https://ccache.samba.org/
278 .. _`run modes`: https://ccache.samba.org/manual.html#_run_modes
279 .. _`configuration`: https://ccache.samba.org/manual.html#_configuration
281 Development-mode cluster
282 ------------------------
284 See :doc:`/dev/quick_guide`.
286 Kubernetes/Rook development cluster
287 -----------------------------------
289 See :ref:`kubernetes-dev`
296 All bugfixes should be merged to the ``main`` branch before being
297 backported. To flag a bugfix for backporting, make sure it has a
298 `tracker issue`_ associated with it and set the ``Backport`` field to a
299 comma-separated list of previous releases (e.g. "hammer,jewel") that you think
301 The rest (including the actual backporting) will be taken care of by the
302 `Stable Releases and Backports`_ team.
304 .. _`tracker issue`: http://tracker.ceph.com/
305 .. _`Stable Releases and Backports`: http://tracker.ceph.com/projects/ceph-releases/wiki
310 Dependabot is a GitHub bot that scans the dependencies in the repositories for
311 security vulnerabilities (CVEs). If a fix is available for a discovered CVE,
312 Dependabot creates a pull request to update the dependency.
314 Dependabot also indicates the compatibility score of the upgrade. This score is
315 based on the number of CI failures that occur in other GitHub repositories
316 where the fix was applied.
318 With some configuration, Dependabot can perform non-security updates (for
319 example, it can upgrade to the latest minor version or patch version).
321 Dependabot supports `several languages and package managers
322 <https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#supported-repositories-and-ecosystems>`_.
323 As of July 2022, the Ceph project receives alerts only from pip (based on the
324 `requirements.txt` files) and npm (`package*.json`). It is possible to extend
325 these alerts to git submodules, Golang, and Java. As of July 2022, there is no
326 support for C++ package managers such as vcpkg, conan, C++20 modules.
328 Many of the dependencies discovered by Dependabot will best be updated
329 elsewhere than the Ceph Github repository (distribution packages, for example,
330 will be a better place to update some of the dependencies). Nonetheless, the
331 list of new and existing vulnerabilities generated by Dependabot will be
334 `Here is an example of a Dependabot pull request.
335 <https://github.com/ceph/ceph/pull/46998>`_
337 Guidance for use of cluster log
338 -------------------------------
340 If your patches emit messages to the Ceph cluster log, please consult
341 this: :doc:`/dev/logging`.