Skip to content

Commit

Permalink
Merge pull request #6780 from smithfarm/wip-index-20151201
Browse files Browse the repository at this point in the history 
doc/dev/index.rst: fix headings

Reviewed-by: Loic Dachary <ldachary@redhat.com>
  • Loading branch information
Loic Dachary committed Dec 3, 2015
2 parents 46493d4 + 6807b35 commit 15a81bb
Showing 1 changed file with 141 additions and 83 deletions.
224 changes: 141 additions & 83 deletions doc/dev/index.rst
View file
@@ -1,9 +1,6 @@
====================
Contributing to Ceph
====================
----------------------
A Guide for Developers
----------------------
============================================
Contributing to Ceph: A Guide for Developers
============================================

:Author: Loic Dachary
:Author: Nathan Cutler
Expand All @@ -12,66 +9,83 @@ A Guide for Developers
.. note:: The old (pre-2016) developer documentation has been moved to :doc:`/dev/index-old`.

.. contents::
:depth: 4
:depth: 3

Introduction
============

This guide assumes that you are already familiar with Ceph (the distributed
This guide has two aims. First, it should lower the barrier to entry for
software developers who wish to get involved in the Ceph project. Second,
it should serve as a reference for Ceph developers.

We assume that readers are already familiar with Ceph (the distributed
object store and file system designed to provide excellent performance,
reliability and scalability). If not, please refer to the `project website`_
and especially the `publications list`_.

.. _`project website`: http://ceph.com
.. _`publications list`: https://ceph.com/resources/publications/

Bare essentials
===============
Since this document is to be consumed by developers, who are assumed to
have Internet access, topics covered elsewhere on the web are treated by
linking. If you notice that a link is broken or if you know of a better
link, `open a pull request`_.

.. _`open a pull request`: http://tracker.ceph.com/projects/ceph/issues/new

The bare essentials
===================

This chapter presents essential information that every Ceph developer needs
to know.

Leads
-----

* Project lead: Sage Weil
* RADOS lead: Samuel Just
* RGW lead: Yehuda Sadeh
* RBD lead: Josh Durgin
* CephFS lead: Gregory Farnum
* Build/Ops lead: Ken Dreyer
The Ceph project is led by Sage Weil. In addition, each major project
component has its own lead. The following table shows all the leads and
their nicks on `GitHub`_:

The Ceph-specific acronyms are explained under `High-level structure`_, below.
.. _github: https://github.com/ceph/ceph

History
-------
========= =============== =============
Scope Lead GitHub nick
========= =============== =============
Ceph Sage Weil liewegas
RADOS Samuel Just athanatos
RGW Yehuda Sadeh yehudasa
RBD Josh Durgin jdurgin
CephFS Gregory Farnum gregsfortytwo
Build/Ops Ken Dreyer ktdreyer
========= =============== =============

The Ceph project grew out of the petabyte-scale storage research at the Storage
Systems Research Center at the University of California, Santa Cruz. The
project was funded primarily by a grant from the Lawrence Livermore, Sandia,
and Los Alamos National Laboratories.
The Ceph-specific acronyms in the table are explained under `High-level
structure`_, below.

Sage Weil, the project lead, published his Ph. D. thesis entitled "Ceph:
Reliable, Scalable, and High-Performance Distributed Storage" in 2007.

DreamHost https://www.dreamhost.com . . .
History
-------

Inktank . . .
See the `History chapter of the Wikipedia article`_.

On April 30, 2014 Red Hat announced its takeover of Inktank:
http://www.redhat.com/en/about/press-releases/red-hat-acquire-inktank-provider-ceph
.. _`History chapter of the Wikipedia article`: https://en.wikipedia.org/wiki/Ceph_%28software%29#History

Licensing
---------

Ceph is free software.

Unless stated otherwise, the Ceph source code is distributed under the terms of
the LGPL2.1. For full details, see the file COPYING in the top-level directory
of the source-code distribution:
https://github.com/ceph/ceph/blob/master/COPYING
the LGPL2.1. For full details, see `the file COPYING in the top-level
directory of the source-code tree`_.

.. _`the file COPYING in the top-level directory of the source-code tree`:
https://github.com/ceph/ceph/blob/master/COPYING

Source code repositories
------------------------

The source code of Ceph lives on GitHub in a number of repositories below https://github.com/ceph
The source code of Ceph lives on GitHub in a number of repositories below
https://github.com/ceph.

To make a meaningful contribution to the project as a developer, a working
knowledge of git_ is essential.
Expand All @@ -81,10 +95,11 @@ knowledge of git_ is essential.
Mailing list
------------

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

subscribe ceph-devel
subscribe ceph-devel

in the body of the message.

Expand All @@ -95,7 +110,13 @@ There are also `other Ceph-related mailing lists`_.
IRC
---

See https://ceph.com/resources/mailing-list-irc/
In addition to mailing lists, the Ceph community also communicates in real
time using `Internet Relay Chat`_.

.. _`Internet Relay Chat`: http://www.irchelp.org/

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


High-level structure
Expand All @@ -104,82 +125,119 @@ High-level structure
Like any other large software project, Ceph consists of a number of components.
Viewed from a very high level, the components are:

* **RADOS**
RADOS
-----

RADOS stands for "Reliable, Autonomic Distributed Object Store". In a Ceph
cluster, all data are stored in objects, and RADOS is the component responsible
for that.

RADOS itself can be further broken down into Monitors, Object Storage Daemons
(OSDs), and clients (librados). Monitors and OSDs are introduced at
:doc:`/start/intro`. The client library is explained at
:doc:`/rados/api/index`.

RGW
---

RGW stands for RADOS Gateway. Using the embedded HTTP server civetweb_, RGW
provides a REST interface to RADOS objects.

RADOS stands for "Reliable, Autonomic Distributed Object Store". In a Ceph
cluster, all data are stored in objects, and RADOS is the component responsible
for that.
.. _civetweb: https://github.com/civetweb/civetweb

RADOS itself can be further broken down into Monitors, Object Storage Daemons
(OSDs), and clients.
A more thorough introduction to RGW can be found at :doc:`/radosgw/index`.

* **RGW**
RBD
---

RGW stands for RADOS Gateway. Using the embedded HTTP server civetweb_, RGW
provides a REST interface to RADOS objects.
RBD stands for RADOS Block Device. It enables a Ceph cluster to store disk
images, and includes in-kernel code enabling RBD images to be mounted.

.. _civetweb: https://github.com/civetweb/civetweb
To delve further into RBD, see :doc:`/rbd/rbd`.

* **RBD**
CephFS
------

RBD stands for RADOS Block Device. It enables a Ceph cluster to store disk
images, and includes in-kernel code enabling RBD images to be mounted.
CephFS is a distributed file system that enables a Ceph cluster to be used as a NAS.

* **CephFS**
File system metadata is managed by Meta Data Server (MDS) daemons. The Ceph
file system is explained in more detail at :doc:`/cephfs/index`.

CephFS is a distributed file system that enables a Ceph cluster to be used as a NAS.
Build/Ops
---------

File system metadata is managed by Meta Data Server (MDS) daemons.
Ceph is regularly built and packaged for a number of major Linux
distributions. At the time of this writing, these included Debian, Ubuntu,
CentOS, openSUSE, and Fedora.

Building
========

Building from source
--------------------

See http://docs.ceph.com/docs/master/install/build-ceph/
See instructions at :doc:`/install/build-ceph`.

Testing
=======

You can start a development mode Ceph cluster, after compiling the source, with::

cd src
install -d -m0755 out dev/osd0
./vstart.sh -n -x -l
# check that it's there
./ceph health
cd src
install -d -m0755 out dev/osd0
./vstart.sh -n -x -l
# check that it's there
./ceph health

WIP
===
Issue tracker
=============

Monitors
--------
The Ceph project has its own issue tracker, http://tracker.ceph.com,
powered by `Redmine`_.

MON stands for "Monitor". Each Ceph cluster has a number of monitor processes.
See **man ceph-mon** or http://docs.ceph.com/docs/master/man/8/ceph-mon/ for
some basic information. The monitor source code lives under **src/mon** in the
tree: https://github.com/ceph/ceph/tree/master/src/mon
.. _Redmine: http://www.redmine.org

OSDs
----
The tracker has a Ceph project with a number of subprojects loosely
corresponding to the project components listed in `High-level structure`_.

OSD stands for Object Storage Daemon. Typically, there is one of these for each
disk in the cluster. See **man ceph-osd** or
http://docs.ceph.com/docs/master/man/8/ceph-osd/ for basic information. The OSD
source code can be found here: https://github.com/ceph/ceph/tree/master/src/osd
Mere `registration`_ automatically grants tracker permissions sufficient to
open new issues and comment on existing ones.

librados
--------
.. _registration: http://tracker.ceph.com/account/register

RADOS also includes an API for writing your own clients that can communicate
directly with a Ceph cluster's underlying object store. The API includes
bindings for popular scripting languages such as Python. For more information,
see the documents under https://github.com/ceph/ceph/tree/master/doc/rados/api
To report a bug or propose a new feature, `jump to the Ceph project`_ and
click on `New issue`_.

Build/Ops
---------
.. _`jump to the Ceph project`: http://tracker.ceph.com/projects/ceph
.. _`New issue`: http://tracker.ceph.com/projects/ceph/issues/new

If you start working on an issue, let the other developers know by adding
an update to the issue. If your tracker permissions have been escalated,
you can change the issue status yourself to reflect reality.

**Meanings of some commonly used statuses**

================ ===========================================
Status Meaning
================ ===========================================
New Initial status
In Progress Somebody is working on it
Need Review Pull request is open with a fix
Pending Backport Fix has been merged, backport(s) pending
Resolved Fix and backports (if any) have been merged
================ ===========================================

If you do not have permission to change the status yourself, don't worry:
someone will probably change it for you, even without asking. You can also
ask for assistance on IRC.

Bugfixing
=========

Ceph supports a number of major Linux distributions and provides packaging for them.
Without bugs, there would be no software, and without software, there would
be no software developers. This chapter explains the Ceph-specific aspects
of the project's bugfixing workflows.

A good understanding of the `Issue tracker`_ chapter is necessary before
you attempt to fix any bugs.

0 comments on commit 15a81bb

Please sign in to comment.