You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by ty...@apache.org on 2016/08/23 19:25:18 UTC
svn commit: r1757419 [5/29] - in /cassandra/site/src/doc: ./ 3.10/
3.10/_images/ 3.10/_sources/ 3.10/_sources/architecture/
3.10/_sources/configuration/ 3.10/_sources/cql/
3.10/_sources/data_modeling/ 3.10/_sources/development/ 3.10/_sources/faq/
3.10/...
Added: cassandra/site/src/doc/3.10/_sources/cql/types.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/cql/types.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/cql/types.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/cql/types.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,518 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier
+
+.. _data-types:
+
+Data Types
+----------
+
+CQL is a typed language and supports a rich set of data types, including :ref:`native types <native-types>`,
+:ref:`collection types <collections>`, :ref:`user-defined types <udts>`, :ref:`tuple types <tuples>` and :ref:`custom
+types <custom-types>`:
+
+.. productionlist::
+ cql_type: `native_type` | `collection_type` | `user_defined_type` | `tuple_type` | `custom_type`
+
+
+.. _native-types:
+
+Native Types
+^^^^^^^^^^^^
+
+The native types supported by CQL are:
+
+.. productionlist::
+ native_type: ASCII
+ : | BIGINT
+ : | BLOB
+ : | BOOLEAN
+ : | COUNTER
+ : | DATE
+ : | DECIMAL
+ : | DOUBLE
+ : | FLOAT
+ : | INET
+ : | INT
+ : | SMALLINT
+ : | TEXT
+ : | TIME
+ : | TIMESTAMP
+ : | TIMEUUID
+ : | TINYINT
+ : | UUID
+ : | VARCHAR
+ : | VARINT
+
+The following table gives additional informations on the native data types, and on which kind of :ref:`constants
+<constants>` each type supports:
+
+=============== ===================== ==================================================================================
+ type constants supported description
+=============== ===================== ==================================================================================
+ ``ascii`` :token:`string` ASCII character string
+ ``bigint`` :token:`integer` 64-bit signed long
+ ``blob`` :token:`blob` Arbitrary bytes (no validation)
+ ``boolean`` :token:`boolean` Either ``true`` or ``false``
+ ``counter`` :token:`integer` Counter column (64-bit signed value). See :ref:`counters` for details
+ ``date`` :token:`integer`, A date (with no corresponding time value). See :ref:`dates` below for details
+ :token:`string`
+ ``decimal`` :token:`integer`, Variable-precision decimal
+ :token:`float`
+ ``double`` :token:`integer` 64-bit IEEE-754 floating point
+ :token:`float`
+ ``float`` :token:`integer`, 32-bit IEEE-754 floating point
+ :token:`float`
+ ``inet`` :token:`string` An IP address, either IPv4 (4 bytes long) or IPv6 (16 bytes long). Note that
+ there is no ``inet`` constant, IP address should be input as strings
+ ``int`` :token:`integer` 32-bit signed int
+ ``smallint`` :token:`integer` 16-bit signed int
+ ``text`` :token:`string` UTF8 encoded string
+ ``time`` :token:`integer`, A time (with no corresponding date value) with nanosecond precision. See
+ :token:`string` :ref:`times` below for details
+ ``timestamp`` :token:`integer`, A timestamp (date and time) with millisecond precision. See :ref:`timestamps`
+ :token:`string` below for details
+ ``timeuuid`` :token:`uuid` Version 1 UUID_, generally used as a “conflict-free” timestamp. Also see
+ :ref:`timeuuid-functions`
+ ``tinyint`` :token:`integer` 8-bit signed int
+ ``uuid`` :token:`uuid` A UUID_ (of any version)
+ ``varchar`` :token:`string` UTF8 encoded string
+ ``varint`` :token:`integer` Arbitrary-precision integer
+=============== ===================== ==================================================================================
+
+.. _counters:
+
+Counters
+~~~~~~~~
+
+The ``counter`` type is used to define *counter columns*. A counter column is a column whose value is a 64-bit signed
+integer and on which 2 operations are supported: incrementing and decrementing (see the :ref:`UPDATE statement
+<update-statement>` for syntax). Note that the value of a counter cannot be set: a counter does not exist until first
+incremented/decremented, and that first increment/decrement is made as if the prior value was 0.
+
+.. _counter-limitations:
+
+Counters have a number of important limitations:
+
+- They cannot be used for columns part of the ``PRIMARY KEY`` of a table.
+- A table that contains a counter can only contain counters. In other words, either all the columns of a table outside
+ the ``PRIMARY KEY`` have the ``counter`` type, or none of them have it.
+- Counters do not support :ref:`expiration <ttls>`.
+- The deletion of counters is supported, but is only guaranteed to work the first time you delete a counter. In other
+ words, you should not re-update a counter that you have deleted (if you do, proper behavior is not guaranteed).
+- Counter updates are, by nature, not `idemptotent <https://en.wikipedia.org/wiki/Idempotence>`__. An important
+ consequence is that if a counter update fails unexpectedly (timeout or loss of connection to the coordinator node),
+ the client has no way to know if the update has been applied or not. In particular, replaying the update may or may
+ not lead to an over count.
+
+.. _timestamps:
+
+Working with timestamps
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Values of the ``timestamp`` type are encoded as 64-bit signed integers representing a number of milliseconds since the
+standard base time known as `the epoch <https://en.wikipedia.org/wiki/Unix_time>`__: January 1 1970 at 00:00:00 GMT.
+
+Timestamps can be input in CQL either using their value as an :token:`integer`, or using a :token:`string` that
+represents an `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ date. For instance, all of the values below are
+valid ``timestamp`` values for Mar 2, 2011, at 04:05:00 AM, GMT:
+
+- ``1299038700000``
+- ``'2011-02-03 04:05+0000'``
+- ``'2011-02-03 04:05:00+0000'``
+- ``'2011-02-03 04:05:00.000+0000'``
+- ``'2011-02-03T04:05+0000'``
+- ``'2011-02-03T04:05:00+0000'``
+- ``'2011-02-03T04:05:00.000+0000'``
+
+The ``+0000`` above is an RFC 822 4-digit time zone specification; ``+0000`` refers to GMT. US Pacific Standard Time is
+``-0800``. The time zone may be omitted if desired (``'2011-02-03 04:05:00'``), and if so, the date will be interpreted
+as being in the time zone under which the coordinating Cassandra node is configured. There are however difficulties
+inherent in relying on the time zone configuration being as expected, so it is recommended that the time zone always be
+specified for timestamps when feasible.
+
+The time of day may also be omitted (``'2011-02-03'`` or ``'2011-02-03+0000'``), in which case the time of day will
+default to 00:00:00 in the specified or default time zone. However, if only the date part is relevant, consider using
+the :ref:`date <dates>` type.
+
+.. _dates:
+
+Working with dates
+^^^^^^^^^^^^^^^^^^
+
+Values of the ``date`` type are encoded as 32-bit unsigned integers representing a number of days with “the epoch” at
+the center of the range (2^31). Epoch is January 1st, 1970
+
+As for :ref:`timestamp <timestamps>`, a date can be input either as an :token:`integer` or using a date
+:token:`string`. In the later case, the format should be ``yyyy-mm-dd`` (so ``'2011-02-03'`` for instance).
+
+.. _times:
+
+Working with times
+^^^^^^^^^^^^^^^^^^
+
+Values of the ``time`` type are encoded as 64-bit signed integers representing the number of nanoseconds since midnight.
+
+As for :ref:`timestamp <timestamps>`, a time can be input either as an :token:`integer` or using a :token:`string`
+representing the time. In the later case, the format should be ``hh:mm:ss[.fffffffff]`` (where the sub-second precision
+is optional and if provided, can be less than the nanosecond). So for instance, the following are valid inputs for a
+time:
+
+- ``'08:12:54'``
+- ``'08:12:54.123'``
+- ``'08:12:54.123456'``
+- ``'08:12:54.123456789'``
+
+
+.. _collections:
+
+Collections
+^^^^^^^^^^^
+
+CQL supports 3 kind of collections: :ref:`maps`, :ref:`sets` and :ref:`lists`. The types of those collections is defined
+by:
+
+.. productionlist::
+ collection_type: MAP '<' `cql_type` ',' `cql_type` '>'
+ : | SET '<' `cql_type` '>'
+ : | LIST '<' `cql_type` '>'
+
+and their values can be inputd using collection literals:
+
+.. productionlist::
+ collection_literal: `map_literal` | `set_literal` | `list_literal`
+ map_literal: '{' [ `term` ':' `term` (',' `term` : `term`)* ] '}'
+ set_literal: '{' [ `term` (',' `term`)* ] '}'
+ list_literal: '[' [ `term` (',' `term`)* ] ']'
+
+Note however that neither :token:`bind_marker` nor ``NULL`` are supported inside collection literals.
+
+Noteworthy characteristics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Collections are meant for storing/denormalizing relatively small amount of data. They work well for things like “the
+phone numbers of a given user”, “labels applied to an email”, etc. But when items are expected to grow unbounded (“all
+messages sent by a user”, “events registered by a sensor”...), then collections are not appropriate and a specific table
+(with clustering columns) should be used. Concretely, (non-frozen) collections have the following noteworthy
+characteristics and limitations:
+
+- Individual collections are not indexed internally. Which means that even to access a single element of a collection,
+ the while collection has to be read (and reading one is not paged internally).
+- While insertion operations on sets and maps never incur a read-before-write internally, some operations on lists do.
+ Further, some lists operations are not idempotent by nature (see the section on :ref:`lists <lists>` below for
+ details), making their retry in case of timeout problematic. It is thus advised to prefer sets over lists when
+ possible.
+
+Please note that while some of those limitations may or may not be removed/improved upon in the future, it is a
+anti-pattern to use a (single) collection to store large amounts of data.
+
+.. _maps:
+
+Maps
+~~~~
+
+A ``map`` is a (sorted) set of key-value pairs, where keys are unique and the map is sorted by its keys. You can define
+and insert a map with::
+
+ CREATE TABLE users (
+ id text PRIMARY KEY,
+ name text,
+ favs map<text, text> // A map of text keys, and text values
+ );
+
+ INSERT INTO users (id, name, favs)
+ VALUES ('jsmith', 'John Smith', { 'fruit' : 'Apple', 'band' : 'Beatles' });
+
+ // Replace the existing map entirely.
+ UPDATE users SET favs = { 'fruit' : 'Banana' } WHERE id = 'jsmith';
+
+Further, maps support:
+
+- Updating or inserting one or more elements::
+
+ UPDATE users SET favs['author'] = 'Ed Poe' WHERE id = 'jsmith';
+ UPDATE users SET favs = favs + { 'movie' : 'Cassablanca', 'band' : 'ZZ Top' } WHERE id = 'jsmith';
+
+- Removing one or more element (if an element doesn't exist, removing it is a no-op but no error is thrown)::
+
+ DELETE favs['author'] FROM users WHERE id = 'jsmith';
+ UPDATE users SET favs = favs - { 'movie', 'band'} WHERE id = 'jsmith';
+
+ Note that for removing multiple elements in a ``map``, you remove from it a ``set`` of keys.
+
+Lastly, TTLs are allowed for both ``INSERT`` and ``UPDATE``, but in both case the TTL set only apply to the newly
+inserted/updated elements. In other words::
+
+ UPDATE users USING TTL 10 SET favs['color'] = 'green' WHERE id = 'jsmith';
+
+will only apply the TTL to the ``{ 'color' : 'green' }`` record, the rest of the map remaining unaffected.
+
+
+.. _sets:
+
+Sets
+~~~~
+
+A ``set`` is a (sorted) collection of unique values. You can define and insert a map with::
+
+ CREATE TABLE images (
+ name text PRIMARY KEY,
+ owner text,
+ tags set<text> // A set of text values
+ );
+
+ INSERT INTO images (name, owner, tags)
+ VALUES ('cat.jpg', 'jsmith', { 'pet', 'cute' });
+
+ // Replace the existing set entirely
+ UPDATE images SET tags = { 'kitten', 'cat', 'lol' } WHERE id = 'jsmith';
+
+Further, sets support:
+
+- Adding one or multiple elements (as this is a set, inserting an already existing element is a no-op)::
+
+ UPDATE images SET tags = tags + { 'gray', 'cuddly' } WHERE name = 'cat.jpg';
+
+- Removing one or multiple elements (if an element doesn't exist, removing it is a no-op but no error is thrown)::
+
+ UPDATE images SET tags = tags - { 'cat' } WHERE name = 'cat.jpg';
+
+Lastly, as for :ref:`maps <maps>`, TTLs if used only apply to the newly inserted values.
+
+.. _lists:
+
+Lists
+~~~~~
+
+.. note:: As mentioned above and further discussed at the end of this section, lists have limitations and specific
+ performance considerations that you should take into account before using them. In general, if you can use a
+ :ref:`set <sets>` instead of list, always prefer a set.
+
+A ``list`` is a (sorted) collection of non-unique values where elements are ordered by there position in the list. You
+can define and insert a list with::
+
+ CREATE TABLE plays (
+ id text PRIMARY KEY,
+ game text,
+ players int,
+ scores list<int> // A list of integers
+ )
+
+ INSERT INTO plays (id, game, players, scores)
+ VALUES ('123-afde', 'quake', 3, [17, 4, 2]);
+
+ // Replace the existing list entirely
+ UPDATE plays SET scores = [ 3, 9, 4] WHERE id = '123-afde';
+
+Further, lists support:
+
+- Appending and prepending values to a list::
+
+ UPDATE plays SET players = 5, scores = scores + [ 14, 21 ] WHERE id = '123-afde';
+ UPDATE plays SET players = 6, scores = [ 3 ] + scores WHERE id = '123-afde';
+
+- Setting the value at a particular position in the list. This imply that the list has a pre-existing element for that
+ position or an error will be thrown that the list is too small::
+
+ UPDATE plays SET scores[1] = 7 WHERE id = '123-afde';
+
+- Removing an element by its position in the list. This imply that the list has a pre-existing element for that position
+ or an error will be thrown that the list is too small. Further, as the operation removes an element from the list, the
+ list size will be diminished by 1, shifting the position of all the elements following the one deleted::
+
+ DELETE scores[1] FROM plays WHERE id = '123-afde';
+
+- Deleting *all* the occurrences of particular values in the list (if a particular element doesn't occur at all in the
+ list, it is simply ignored and no error is thrown)::
+
+ UPDATE plays SET scores = scores - [ 12, 21 ] WHERE id = '123-afde';
+
+.. warning:: The append and prepend operations are not idempotent by nature. So in particular, if one of these operation
+ timeout, then retrying the operation is not safe and it may (or may not) lead to appending/prepending the value
+ twice.
+
+.. warning:: Setting and removing an element by position and removing occurences of particular values incur an internal
+ *read-before-write*. They will thus run more slowly and take more ressources than usual updates (with the exclusion
+ of conditional write that have their own cost).
+
+Lastly, as for :ref:`maps <maps>`, TTLs when used only apply to the newly inserted values.
+
+.. _udts:
+
+User-Defined Types
+^^^^^^^^^^^^^^^^^^
+
+CQL support the definition of user-defined types (UDT for short). Such a type can be created, modified and removed using
+the :token:`create_type_statement`, :token:`alter_type_statement` and :token:`drop_type_statement` described below. But
+once created, a UDT is simply referred to by its name:
+
+.. productionlist::
+ user_defined_type: `udt_name`
+ udt_name: [ `keyspace_name` '.' ] `identifier`
+
+
+Creating a UDT
+~~~~~~~~~~~~~~
+
+Creating a new user-defined type is done using a ``CREATE TYPE`` statement defined by:
+
+.. productionlist::
+ create_type_statement: CREATE TYPE [ IF NOT EXISTS ] `udt_name`
+ : '(' `field_definition` ( ',' `field_definition` )* ')'
+ field_definition: `identifier` `cql_type`
+
+A UDT has a name (used to declared columns of that type) and is a set of named and typed fields. Fields name can be any
+type, including collections or other UDT. For instance::
+
+ CREATE TYPE phone (
+ country_code int,
+ number text,
+ )
+
+ CREATE TYPE address (
+ street text,
+ city text,
+ zip int,
+ phones map<text, phone>
+ )
+
+ CREATE TABLE user (
+ name text PRIMARY KEY,
+ addresses map<text, frozen<address>>
+ )
+
+Note that:
+
+- Attempting to create an already existing type will result in an error unless the ``IF NOT EXISTS`` option is used. If
+ it is used, the statement will be a no-op if the type already exists.
+- A type is intrinsically bound to the keyspace in which it is created, and can only be used in that keyspace. At
+ creation, if the type name is prefixed by a keyspace name, it is created in that keyspace. Otherwise, it is created in
+ the current keyspace.
+- As of Cassandra |version|, UDT have to be frozen in most cases, hence the ``frozen<address>`` in the table definition
+ above. Please see the section on :ref:`frozen <frozen>` for more details.
+
+UDT literals
+~~~~~~~~~~~~
+
+Once a used-defined type has been created, value can be input using a UDT literal:
+
+.. productionlist::
+ udt_literal: '{' `identifier` ':' `term` ( ',' `identifier` ':' `term` )* '}'
+
+In other words, a UDT literal is like a :ref:`map <maps>` literal but its keys are the names of the fields of the type.
+For instance, one could insert into the table define in the previous section using::
+
+ INSERT INTO user (name, addresses)
+ VALUES ('z3 Pr3z1den7', {
+ 'home' : {
+ street: '1600 Pennsylvania Ave NW',
+ city: 'Washington',
+ zip: '20500',
+ phones: { 'cell' : { country_code: 1, number: '202 456-1111' },
+ 'landline' : { country_code: 1, number: '...' } }
+ }
+ 'work' : {
+ street: '1600 Pennsylvania Ave NW',
+ city: 'Washington',
+ zip: '20500',
+ phones: { 'fax' : { country_code: 1, number: '...' } }
+ }
+ })
+
+To be valid, a UDT literal should only include fields defined by the type it is a literal of, but it can omit some field
+(in which case those will be ``null``).
+
+Altering a UDT
+~~~~~~~~~~~~~~
+
+An existing user-defined type can be modified using an ``ALTER TYPE`` statement:
+
+.. productionlist::
+ alter_type_statement: ALTER TYPE `udt_name` `alter_type_modification`
+ alter_type_modification: ALTER `identifier` TYPE `cql_type`
+ : | ADD `field_definition`
+ : | RENAME `identifier` TO `identifier` ( `identifier` TO `identifier` )*
+
+You can:
+
+- modify the type of particular field (``ALTER TYPE address ALTER zip TYPE bigint``). The restrictions for such change
+ are the same than when :ref:`altering the type of column <alter-table-statement>`.
+- add a new field to the type (``ALTER TYPE address ADD country text``). That new field will be ``null`` for any values
+ of the type created before the addition.
+- rename the fields of the type (``ALTER TYPE address RENAME zip TO zipcode``).
+
+Dropping a UDT
+~~~~~~~~~~~~~~
+
+You can drop an existing user-defined type using a ``DROP TYPE`` statement:
+
+.. productionlist::
+ drop_type_statement: DROP TYPE [ IF EXISTS ] `udt_name`
+
+Dropping a type results in the immediate, irreversible removal of that type. However, attempting to drop a type that is
+still in use by another type, table or function will result in an error.
+
+If the type dropped does not exist, an error will be returned unless ``IF EXISTS`` is used, in which case the operation
+is a no-op.
+
+.. _tuples:
+
+Tuples
+^^^^^^
+
+CQL also support tuples and tuple types (where the elements can be of different types). Functionally, tuples can be
+though as anonymous UDT with anonymous fields. Tuple types and tuple literals are defined by:
+
+.. productionlist::
+ tuple_type: TUPLE '<' `cql_type` ( ',' `cql_type` )* '>'
+ tuple_literal: '(' `term` ( ',' `term` )* ')'
+
+and can be used thusly::
+
+ CREATE TABLE durations (
+ event text,
+ duration tuple<int, text>,
+ )
+
+ INSERT INTO durations (event, duration) VALUES ('ev1', (3, 'hours'));
+
+Unlike other "composed" types (collections and UDT), a tuple is always :ref:`frozen <frozen>` (without the need of the
+`frozen` keyword) and it is not possible to update only some elements of a tuple (without updating the whole tuple).
+Also, a tuple literal should always have the same number of value than declared in the type it is a tuple of (some of
+those values can be null but they need to be explicitly declared as so).
+
+.. _custom-types:
+
+Custom Types
+^^^^^^^^^^^^
+
+.. note:: Custom types exists mostly for backward compatiliby purposes and their usage is discouraged. Their usage is
+ complex, not user friendly and the other provided types, particularly :ref:`user-defined types <udts>`, should almost
+ always be enough.
+
+A custom type is defined by:
+
+.. productionlist::
+ custom_type: `string`
+
+A custom type is a :token:`string` that contains the name of Java class that extends the server side ``AbstractType``
+class and that can be loaded by Cassandra (it should thus be in the ``CLASSPATH`` of every node running Cassandra). That
+class will define what values are valid for the type and how the time sorts when used for a clustering column. For any
+other purpose, a value of a custom type is the same than that of a ``blob``, and can in particular be input using the
+:token:`blob` literal syntax.
Added: cassandra/site/src/doc/3.10/_sources/data_modeling/index.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/data_modeling/index.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/data_modeling/index.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/data_modeling/index.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,20 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Data Modeling
+=============
+
+.. todo:: TODO
Added: cassandra/site/src/doc/3.10/_sources/development/code_style.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/development/code_style.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/development/code_style.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/development/code_style.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,94 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Code Style
+==========
+
+General Code Conventions
+------------------------
+
+ - The Cassandra project follows `Sun's Java coding conventions <http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html>`_ with an important exception: ``{`` and ``}`` are always placed on a new line
+
+Exception handling
+------------------
+
+ - Never ever write ``catch (...) {}`` or ``catch (...) { logger.error() }`` merely to satisfy Java's compile-time exception checking. Always propagate the exception up or throw ``RuntimeException`` (or, if it "can't happen," ``AssertionError``). This makes the exceptions visible to automated tests.
+ - Avoid propagating up checked exceptions that no caller handles. Rethrow as ``RuntimeException`` (or ``IOError``, if that is more applicable).
+ - Similarly, logger.warn() is often a cop-out: is this an error or not? If it is don't hide it behind a warn; if it isn't, no need for the warning.
+ - If you genuinely know an exception indicates an expected condition, it's okay to ignore it BUT this must be explicitly explained in a comment.
+
+Boilerplate
+-----------
+
+ - Avoid redundant ``@Override`` annotations when implementing abstract or interface methods.
+ - Do not implement equals or hashcode methods unless they are actually needed.
+ - Prefer public final fields to private fields with getters. (But prefer encapsulating behavior in "real" methods to either.)
+ - Prefer requiring initialization in the constructor to setters.
+ - Avoid redundant ``this`` references to member fields or methods.
+ - Do not extract interfaces (or abstract classes) unless you actually need multiple implementations of it.
+ - Always include braces for nested levels of conditionals and loops. Only avoid braces for single level.
+
+Multiline statements
+--------------------
+
+ - Try to keep lines under 120 characters, but use good judgement -- it's better to exceed 120 by a little, than split a line that has no natural splitting points.
+ - When splitting inside a method call, use one line per parameter and align them, like this:
+
+ ::
+
+ SSTableWriter writer = new SSTableWriter(cfs.getTempSSTablePath(),
+ columnFamilies.size(),
+ StorageService.getPartitioner());
+
+ - When splitting a ternary, use one line per clause, carry the operator, and align like this:
+
+ ::
+
+ var = bar == null
+ ? doFoo()
+ : doBar();
+
+Whitespace
+----------
+
+ - Please make sure to use 4 spaces instead of the tab character for all your indentation.
+ - Many lines in many files have a bunch of trailing whitespace... Please either clean these up in a separate patch, or leave them alone, so that reviewers now and anyone reading code history later doesn't have to pay attention to whitespace diffs.
+
+Imports
+-------
+
+Please observe the following order for your imports::
+
+ java
+ [blank line]
+ com.google.common
+ org.apache.commons
+ org.junit
+ org.slf4j
+ [blank line]
+ everything else alphabetically
+
+Format files for IDEs
+---------------------
+
+ - IntelliJ: `intellij-codestyle.jar <https://wiki.apache.org/cassandra/CodeStyle?action=AttachFile&do=view&target=intellij-codestyle.jar>`_
+ - IntelliJ 13: `gist for IntelliJ 13 <https://gist.github.com/jdsumsion/9ab750a05c2a567c6afc>`_ (this is a work in progress, still working on javadoc, ternary style, line continuations, etc)
+ - Eclipse (https://github.com/tjake/cassandra-style-eclipse)
+
+
+
Added: cassandra/site/src/doc/3.10/_sources/development/how_to_commit.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/development/how_to_commit.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/development/how_to_commit.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/development/how_to_commit.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,75 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+How-to Commit
+=============
+
+If you are a committer, feel free to pick any process that works for you - so long as you are planning to commit the work yourself.
+
+Here is how committing and merging will usually look for merging and pushing for tickets that follow the convention (if patch-based):
+
+Hypothetical CASSANDRA-12345 ticket is a cassandra-3.0 based bug fix that requires different code for cassandra-3.3, and trunk. Contributor Jackie supplied a patch for the root branch (12345-3.0.patch), and patches for the remaining branches (12345-3.3.patch, 12345-trunk.patch).
+
+On cassandra-3.0:
+ #. ``git am -3 12345-3.0.patch`` (if we have a problem b/c of CHANGES.txt not merging anymore, we fix it ourselves, in place)
+
+On cassandra-3.3:
+ #. ``git merge cassandra-3.0 -s ours``
+ #. ``git apply -3 12345-3.3.patch`` (likely to have an issue with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt)
+ #. ``git commit —amend``
+
+On trunk:
+ #. ``git merge cassandra-3.3 -s ours``
+ #. ``git apply -3 12345-trunk.patch`` (likely to have an issue with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt)
+ #. ``git commit —amend``
+
+On any branch:
+ #. ``git push origin cassandra-3.0 cassandra-3.3 trunk —atomic``
+
+Same scenario, but a branch-based contribution:
+
+On cassandra-3.0:
+ #. ``git cherry-pick <sha-of-3.0-commit>`` (if we have a problem b/c of CHANGES.txt not merging anymore, we fix it ourselves, in place)
+
+On cassandra-3.3:
+ #. ``git merge cassandra-3.0 -s ours``
+ #. ``git format-patch -1 <sha-of-3.3-commit>``
+ #. ``git apply -3 <sha-of-3.3-commit>.patch`` (likely to have an issue with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt)
+ #. ``git commit —amend``
+
+On trunk:
+ #. ``git merge cassandra-3.3 -s ours``
+ #. ``git format-patch -1 <sha-of-trunk-commit>``
+ #. ``git apply -3 <sha-of-trunk-commit>.patch`` (likely to have an issue with CHANGES.txt here: fix it ourselves, then git add CHANGES.txt)
+ #. ``git commit —amend``
+
+On any branch:
+ #. ``git push origin cassandra-3.0 cassandra-3.3 trunk —atomic``
+
+.. tip::
+
+ Notes on git flags:
+ ``-3`` flag to am and apply will instruct git to perform a 3-way merge for you. If a conflict is detected, you can either resolve it manually or invoke git mergetool - for both am and apply.
+
+ ``—atomic`` flag to git push does the obvious thing: pushes all or nothing. Without the flag, the command is equivalent to running git push once per each branch. This is nifty in case a race condition happens - you won’t push half the branches, blocking other committers’ progress while you are resolving the issue.
+
+.. tip::
+
+ The fastest way to get a patch from someone’s commit in a branch on GH - if you don’t have their repo in remotes - is to append .patch to the commit url, e.g.
+ curl -O https://github.com/apache/cassandra/commit/7374e9b5ab08c1f1e612bf72293ea14c959b0c3c.patch
+
Added: cassandra/site/src/doc/3.10/_sources/development/how_to_review.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/development/how_to_review.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/development/how_to_review.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/development/how_to_review.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,71 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Review Checklist
+****************
+
+When reviewing tickets in Apache JIRA, the following items should be covered as part of the review process:
+
+**General**
+
+ * Does it conform to the :doc:`code_style` guidelines?
+ * Is there any redundant or duplicate code?
+ * Is the code as modular as possible?
+ * Can any singletons be avoided?
+ * Can any of the code be replaced with library functions?
+ * Are units of measurement used in the code consistent, both internally and with the rest of the ecosystem?
+
+**Error-Handling**
+
+ * Are all data inputs and outputs checked (for the correct type, length, format, and range) and encoded?
+ * Where third-party utilities are used, are returning errors being caught?
+ * Are invalid parameter values handled?
+ * Are any Throwable/Exceptions passed to the JVMStabilityInspector?
+ * Are errors well-documented? Does the error message tell the user how to proceed?
+ * Do exceptions propagate to the appropriate level in the code?
+
+**Documentation**
+
+ * Do comments exist and describe the intent of the code (the "why", not the "how")?
+ * Are javadocs added where appropriate?
+ * Is any unusual behavior or edge-case handling described?
+ * Are data structures and units of measurement explained?
+ * Is there any incomplete code? If so, should it be removed or flagged with a suitable marker like ‘TODO’?
+ * Does the code self-document via clear naming, abstractions, and flow control?
+ * Have NEWS.txt, the cql3 docs, and the native protocol spec been updated if needed?
+ * Is the ticket tagged with "client-impacting" and "doc-impacting", where appropriate?
+ * Has lib/licences been updated for third-party libs? Are they Apache License compatible?
+ * Is the Component on the JIRA ticket set appropriately?
+
+**Testing**
+
+ * Is the code testable? i.e. don’t add too many or hide dependencies, unable to initialize objects, test frameworks can use methods etc.
+ * Do tests exist and are they comprehensive?
+ * Do unit tests actually test that the code is performing the intended functionality?
+ * Could any test code use common functionality (e.g. ccm, dtest, or CqlTester methods) or abstract it there for reuse?
+ * If the code may be affected by multi-node clusters, are there dtests?
+ * If the code may take a long time to test properly, are there CVH tests?
+ * Is the test passing on CI for all affected branches (up to trunk, if applicable)? Are there any regressions?
+ * If patch affects read/write path, did we test for performance regressions w/multiple workloads?
+ * If adding a new feature, were tests added and performed confirming it meets the expected SLA/use-case requirements for the feature?
+
+**Logging**
+
+ * Are logging statements logged at the correct level?
+ * Are there logs in the critical path that could affect performance?
+ * Is there any log that could be added to communicate status or troubleshoot potential problems in this feature?
+ * Can any unnecessary logging statement be removed?
+
Added: cassandra/site/src/doc/3.10/_sources/development/ide.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/development/ide.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/development/ide.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/development/ide.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,157 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Building and IDE Integration
+****************************
+
+Building From Source
+====================
+
+Getting started with Cassandra and IntelliJ IDEA or Eclipse is simple, once you manage to build Cassandra from source using `Java 8 <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_, `Git <https://git-scm.com/>`_ and `Ant <http://ant.apache.org/>`_.
+
+The source code for Cassandra is shared through the central Apache Git repository and organized by different branches. You can access the code for the current development branch through git as follows::
+
+ git clone http://git-wip-us.apache.org/repos/asf/cassandra.git cassandra-trunk
+
+Other branches will point to different versions of Cassandra. Switching to a different branch requires checking out the branch by its name::
+
+ git checkout cassandra-3.0
+
+You can get a list of available branches with ``git branch``.
+
+Finally build Cassandra using ant::
+
+ ant
+
+This may take a significant amount of time depending on whether artifacts have to be downloaded and the number of classes that need to be compiled.
+
+.. hint::
+
+ You can setup multiple working trees for different Cassandra versions from the same repository using `git-worktree <https://git-scm.com/docs/git-worktree>`_.
+
+Setting up Cassandra in IntelliJ IDEA
+=====================================
+
+`IntelliJ IDEA <https://www.jetbrains.com/idea/>`_ by JetBrains is one of the most popular IDEs for Cassandra and Java development in general. The Community Edition is provided as a free download with all features needed to get started developing Cassandra.
+
+Setup Cassandra as a Project (C* 2.1 and newer)
+-----------------------------------------------
+
+Since 2.1.5, there is a new ant target: ``generate-idea-files``. Please see our `wiki <https://wiki.apache.org/cassandra/RunningCassandraInIDEA>`_ for instructions for older Cassandra versions.
+
+Please clone and build Cassandra as described above and execute the following steps:
+
+1. Once Cassandra is built, generate the IDEA files using ant:
+
+::
+
+ ant generate-idea-files
+
+2. Start IDEA
+
+3. Open the IDEA project from the checked out Cassandra directory using the menu item Open in IDEA's File menu
+
+The project generated by the ant task ``generate-idea-files`` contains nearly everything you need to debug Cassandra and execute unit tests.
+
+ * Run/debug defaults for JUnit
+ * Run/debug configuration for Cassandra daemon
+ * License header for Java source files
+ * Cassandra code style
+ * Inspections
+
+Setting up Cassandra in Eclipse
+===============================
+
+Eclipse is a popular open source IDE that can be used for Cassandra development. Various Eclipse environments are available from the `download page <https://www.eclipse.org/downloads/eclipse-packages/>`_. The following guide was created with "Eclipse IDE for Java Developers".
+
+These instructions were tested on Ubuntu 16.04 with Eclipse Neon (4.6) using Cassandra 2.1, 2.2 and 3.x.
+
+Project Settings
+----------------
+
+**It is important that you generate the Eclipse files with Ant before trying to set up the Eclipse project.**
+
+ * Clone and build Cassandra as described above.
+ * Run ``ant generate-eclipse-files`` to create the Eclipse settings.
+ * Start Eclipse.
+ * Select ``File->Import->Existing Projects into Workspace->Select git directory``.
+ * Make sure "cassandra-trunk" is recognized and selected as a project (assuming you checked the code out into the folder cassandra-trunk as described above).
+ * Confirm "Finish" to have your project imported.
+
+You should now be able to find the project as part of the "Package Explorer" or "Project Explorer" without having Eclipse complain about any errors after building the project automatically.
+
+Unit Tests
+----------
+
+Unit tests can be run from Eclipse by simply right-clicking the class file or method and selecting ``Run As->JUnit Test``. Tests can be debugged this way as well by defining breakpoints (double-click line number) and selecting ``Debug As->JUnit Test``.
+
+Alternatively all unit tests can be run from the command line as described in :doc:`testing`
+
+Debugging Cassandra Using Eclipse
+---------------------------------
+
+There are two ways how to start and debug a local Cassandra instance with Eclipse. You can either start Cassandra just as you normally would by using the ``./bin/cassandra`` script and connect to the JVM through `remotely <https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/introclientissues005.html>`_ from Eclipse or start Cassandra from Eclipse right away.
+
+Starting Cassandra From Command Line
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ * Set environment variable to define remote debugging options for the JVM:
+ ``export JVM_EXTRA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=1414"``
+ * Start Cassandra by executing the ``./bin/cassandra``
+
+Afterwards you should be able to connect to the running Cassandra process through the following steps:
+
+From the menu, select ``Run->Debug Configurations..``
+
+.. image:: images/eclipse_debug0.png
+
+Create new remote application
+
+.. image:: images/eclipse_debug1.png
+
+Configure connection settings by specifying a name and port 1414
+
+.. image:: images/eclipse_debug2.png
+
+Afterwards confirm "Debug" to connect to the JVM and start debugging Cassandra!
+
+Starting Cassandra From Eclipse
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Cassandra can also be started directly from Eclipse if you don't want to use the command line.
+
+From the menu, select ``Run->Run Configurations..``
+
+.. image:: images/eclipse_debug3.png
+
+Create new application
+
+.. image:: images/eclipse_debug4.png
+
+Specify name, project and main class ``org.apache.cassandra.service.CassandraDaemon``
+
+.. image:: images/eclipse_debug5.png
+
+Configure additional JVM specific parameters that will start Cassandra with some of the settings created by the regular startup script. Change heap related values as needed.
+
+::
+
+ -Xms1024M -Xmx1024M -Xmn220M -Xss256k -ea -XX:+UseThreadPriorities -XX:ThreadPriorityPolicy=42 -XX:+UseParNewGC -XX:+UseConcMarkSweepGC -XX:+CMSParallelRemarkEnabled -XX:+UseCondCardMark -javaagent:./lib/jamm-0.3.0.jar -Djava.net.preferIPv4Stack=true
+
+.. image:: images/eclipse_debug6.png
+
+Now just confirm "Debug" and you should see the output of Cassandra starting up in the Eclipse console and should be able to set breakpoints and start debugging!
+
Added: cassandra/site/src/doc/3.10/_sources/development/index.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/development/index.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/development/index.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/development/index.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,28 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Cassandra Development
+*********************
+
+.. toctree::
+ :maxdepth: 2
+
+ ide
+ testing
+ patches
+ code_style
+ how_to_review
+ how_to_commit
Added: cassandra/site/src/doc/3.10/_sources/development/patches.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/development/patches.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/development/patches.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/development/patches.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,125 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Contributing Code Changes
+*************************
+
+Choosing What to Work on
+========================
+
+Submitted patches can include bug fixes, changes to the Java code base, improvements for tooling (both Java or Python), documentation, testing or any other changes that requires changing the code base. Although the process of contributing code is always the same, the amount of work and time it takes to get a patch accepted also depends on the kind of issue you're addressing.
+
+As a general rule of thumb:
+ * Major new features and significant changes to the code based will likely not going to be accepted without deeper discussion within the `developer community <http://cassandra.apache.org/community/>`_
+ * Bug fixes take higher priority compared to features
+ * The extend to which tests are required depend on how likely your changes will effect the stability of Cassandra in production. Tooling changes requires fewer tests than storage engine changes.
+ * Less complex patches will be faster to review: consider breaking up an issue into individual tasks and contributions that can be reviewed separately
+
+.. hint::
+
+ Not sure what to work? Just pick an issue tagged with the `low hanging fruit label <https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+=+12310865+AND+labels+=+lhf+AND+status+!=+resolved>`_ in JIRA, which we use to flag issues that could turn out to be good starter tasks for beginners.
+
+Before You Start Coding
+=======================
+
+Although contributions are highly appreciated, we do not guarantee that each contribution will become a part of Cassandra. Therefor it's generally a good idea to first get some feedback on the things you plan to work on, especially about any new features or major changes to the code base. You can reach out to other developers on the mailing list or IRC channel listed on our `community page <http://cassandra.apache.org/community/>`_.
+
+You should also
+ * Avoid redundant work by searching for already reported issues in `JIRA <https://issues.apache.org/jira/browse/CASSANDRA>`_
+ * Create a new issue early in the process describing what you're working on - not just after finishing your patch
+ * Link related JIRA issues with your own ticket to provide a better context
+ * Update your ticket from time to time by giving feedback on your progress and link a GitHub WIP branch with your current code
+ * Ping people who you actively like to ask for advice on JIRA by `mentioning users <https://confluence.atlassian.com/conf54/confluence-user-s-guide/sharing-content/using-mentions>`_
+
+There are also some fixed rules that you need to be aware:
+ * Patches will only be applied to branches by following the release model
+ * Code must be testable
+ * Code must follow the :doc:`code_style` convention
+ * Changes must not break compatibility between different Cassandra versions
+ * Contributions must be covered by the Apache License
+
+Choosing the Right Branches to Work on
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are currently multiple Cassandra versions maintained in individual branches:
+
+======= ======
+Version Policy
+======= ======
+3.x Tick-tock (see below)
+3.0 Bug fixes only
+2.2 Bug fixes only
+2.1 Critical bug fixes only
+======= ======
+
+Corresponding branches in git are easy to recognize as they are named ``cassandra-<release>`` (e.g. ``cassandra-3.0``). The ``trunk`` branch is an exception, as it contains the most recent commits from all other branches and is used for creating new branches for future tick-tock releases.
+
+Tick-Tock Releases
+""""""""""""""""""
+
+New releases created as part of the `tick-tock release process <http://www.planetcassandra.org/blog/cassandra-2-2-3-0-and-beyond/>`_ will either focus on stability (odd version numbers) or introduce new features (even version numbers). Any code for new Cassandra features you should be based on the latest, unreleased 3.x branch with even version number or based on trunk.
+
+Bug Fixes
+"""""""""
+
+Creating patches for bug fixes is a bit more complicated as this will depend on how many different versions of Cassandra are affected. In each case, the order for merging such changes will be ``cassandra-2.1`` -> ``cassandra-2.2`` -> ``cassandra-3.0`` -> ``cassandra-3.x`` -> ``trunk``. But don't worry, merging from 2.1 would be the worst case for bugs that affect all currently supported versions, which isn't very common. As a contributor, you're also not expected to provide a single patch for each version. What you need to do however is:
+
+ * Be clear about which versions you could verify to be affected by the bug
+ * For 2.x: ask if a bug qualifies to be fixed in this release line, as this may be handled on case by case bases
+ * If possible, create a patch against the lowest version in the branches listed above (e.g. if you found the bug in 3.9 you should try to fix it already in 3.0)
+ * Test if the patch can be merged cleanly across branches in the direction listed above
+ * Be clear which branches may need attention by the committer or even create custom patches for those if you can
+
+Creating a Patch
+================
+
+So you've finished coding and the great moment arrives: it's time to submit your patch!
+
+ 1. Create a branch for your changes if you haven't done already. Many contributors name their branches based on ticket number and Cassandra version, e.g. ``git checkout -b 12345-3.0``
+ 2. Verify that you follow Cassandra's :doc:`code_style`
+ 3. Make sure all tests (including yours) pass using ant as described in :doc:`testing`. If you suspect a test failure is unrelated to your change, it may be useful to check the test's status by searching the issue tracker or looking at `CI <https://cassci.datastax.com/>`_ results for the relevant upstream version. Note that the full test suites take many hours to complete, so it is common to only run specific relevant tests locally before uploading a patch. Once a patch has been uploaded, the reviewer or committer can help setup CI jobs to run the full test suites.
+ 4. Consider going through the :doc:`how_to_review` for your code. This will help you to understand how others will consider your change for inclusion.
+ 5. Don’t make the committer squash commits for you in the root branch either. Multiple commits are fine - and often preferable - during review stage, especially for incremental review, but once +1d, do either:
+
+ a. Attach a patch to JIRA with a single squashed commit in it (per branch), or
+ b. Squash the commits in-place in your branches into one
+
+ 6. Include a CHANGES.txt entry (put it at the top of the list), and format the commit message appropriately in your patch ending with the following statement on the last line: ``patch by X; reviewed by Y for CASSANDRA-ZZZZZ``
+ 7. When you're happy with the result, create a patch:
+
+ ::
+
+ git add <any new or modified file>
+ git commit -m '<message>'
+ git format-patch HEAD~1
+ mv <patch-file> <ticket-branchname.txt> (e.g. 12345-trunk.txt, 12345-3.0.txt)
+
+ Alternatively, many contributors prefer to make their branch available on GitHub. In this case, fork the Cassandra repository on GitHub and push your branch:
+
+ ::
+
+ git push --set-upstream origin 12345-3.0
+
+ 8. To make life easier for your reviewer/committer, you may want to make sure your patch applies cleanly to later branches and create additional patches/branches for later Cassandra versions to which your original patch does not apply cleanly. That said, this is not critical, and you will receive feedback on your patch regardless.
+ 9. Attach the newly generated patch to the ticket/add a link to your branch and click "Submit Patch" at the top of the ticket. This will move the ticket into "Patch Available" status, indicating that your submission is ready for review.
+ 10. Wait for other developers or committers to review it and hopefully +1 the ticket (see :doc:`how_to_review`). If your change does not receive a +1, do not be discouraged. If possible, the reviewer will give suggestions to improve your patch or explain why it is not suitable.
+ 11. If the reviewer has given feedback to improve the patch, make the necessary changes and move the ticket into "Patch Available" once again.
+
+Once the review process is complete, you will receive a +1. Wait for a committer to commit it. Do not delete your branches immediately after they’ve been committed - keep them on GitHub for a while. Alternatively, attach a patch to JIRA for historical record. It’s not that uncommon for a committer to mess up a merge. In case of that happening, access to the original code is required, or else you’ll have to redo some of the work.
+
+
Added: cassandra/site/src/doc/3.10/_sources/development/testing.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/development/testing.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/development/testing.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/development/testing.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,86 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Testing
+*******
+
+Creating tests is one of the most important and also most difficult parts of developing Cassandra. There are different ways to test your code depending on what you're working on.
+
+
+Unit Testing
+============
+
+The most simple way to test code in Cassandra is probably by writing a unit test. Cassandra uses JUnit as a testing framework and test cases can be found in the ``test/unit`` directory. Ideally you’d be able to create a unit test for your implementation that would exclusively cover the class you created (the unit under test). Unfortunately this is not always possible and Cassandra doesn’t have a very mock friendly code base. Often you’ll find yourself in a situation where you have to make use of an embedded Cassandra instance that you’ll be able to interact with in your test. If you want to make use of CQL in your test, you can simply extend CQLTester and use some of the convenient helper methods such as in the following example.
+
+.. code-block:: java
+
+ @Test
+ public void testBatchAndList() throws Throwable
+ {
+ createTable("CREATE TABLE %s (k int PRIMARY KEY, l list<int>)");
+ execute("BEGIN BATCH " +
+ "UPDATE %1$s SET l = l +[ 1 ] WHERE k = 0; " +
+ "UPDATE %1$s SET l = l + [ 2 ] WHERE k = 0; " +
+ "UPDATE %1$s SET l = l + [ 3 ] WHERE k = 0; " +
+ "APPLY BATCH");
+
+ assertRows(execute("SELECT l FROM %s WHERE k = 0"),
+ row(list(1, 2, 3)));
+ }
+
+Unit tests can be run from the command line using the ``ant test`` command, ``ant test -Dtest.name=<simple_classname>`` to execute a test suite or ``ant testsome -Dtest.name=<FQCN> -Dtest.methods=<testmethod1>[,testmethod2]`` for individual tests. For example, to run all test methods in the ``org.apache.cassandra.cql3.SimpleQueryTest`` class, you would run::
+
+ ant test -Dtest.name=SimpleQueryTest
+
+To run only the ``testStaticCompactTables()`` test method from that class, you would run::
+
+ ant testsome -Dtest.name=org.apache.cassandra.cql3.SimpleQueryTest -Dtest.methods=testStaticCompactTables
+
+Long running tests
+------------------
+
+Test that consume a significant amount of time during execution can be found in the ``test/long`` directory and executed as a regular JUnit test or standalone program. Except for the execution time, there’s nothing really special about them. However, ant will execute tests under ``test/long`` only when using the ``ant long-test`` target.
+
+DTests
+======
+
+One way of doing integration or system testing at larger scale is by using `dtest <https://github.com/riptano/cassandra-dtest>`_, which stands for “Cassandra Distributed Tests”. The idea is to automatically setup Cassandra clusters using various configurations and simulate certain use cases you want to test. This is done using Python scripts and ``ccmlib`` from the `ccm <https://github.com/pcmanus/ccm>`_ project. Dtests will setup clusters using this library just as you do running ad-hoc ``ccm`` commands on your local machine. Afterwards dtests will use the `Python driver <http://datastax.github.io/python-driver/installation.html>`_ to interact with the nodes, manipulate the file system, analyze logs or mess with individual nodes.
+
+Using dtests helps us to prevent regression bugs by continually executing tests on the `CI server <http://cassci.datastax.com/>`_ against new patches. For frequent contributors, this Jenkins is set up to build branches from their GitHub repositories. It is likely that your reviewer will use this Jenkins instance to run tests for your patch. Read more on the motivation behind the CI server `here <http://www.datastax.com/dev/blog/cassandra-testing-improvements-for-developer-convenience-and-confidence>`_.
+
+The best way to learn how to write dtests is probably by reading the introduction "`How to Write a Dtest <http://www.datastax.com/dev/blog/how-to-write-a-dtest>`_" and by looking at existing, recently updated tests in the project. New tests must follow certain `style conventions <https://github.com/riptano/cassandra-dtest/blob/master/CONTRIBUTING.md>`_ that are being checked before accepting contributions. In contrast to Cassandra, dtest issues and pull-requests are managed on github, therefor you should make sure to link any created dtests in your Cassandra ticket and also refer to the ticket number in your dtest PR.
+
+Creating a good dtest can be tough, but it should not prevent you from submitting patches! Please ask in the corresponding JIRA ticket how to write a good dtest for the patch. In most cases a reviewer or committer will able to support you, and in some cases they may offer to write a dtest for you.
+
+Performance Testing
+===================
+
+Performance tests for Cassandra are a special breed of tests that are not part of the usual patch contribution process. In fact you can contribute tons of patches to Cassandra without ever running performance tests. They are important however when working on performance improvements, as such improvements must be measurable.
+
+Cassandra Stress Tool
+---------------------
+
+TODO: `CASSANDRA-12365 <https://issues.apache.org/jira/browse/CASSANDRA-12365>`_
+
+cstar_perf
+----------
+
+Another tool available on github is `cstar_perf <https://github.com/datastax/cstar_perf>`_ that can be used for intensive performance testing in large clusters or locally. Please refer to the project page on how to set it up and how to use it.
+
+
+
Added: cassandra/site/src/doc/3.10/_sources/faq/index.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/faq/index.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/faq/index.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/faq/index.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,298 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Frequently Asked Questions
+==========================
+
+- :ref:`why-cant-list-all`
+- :ref:`what-ports`
+- :ref:`what-happens-on-joins`
+- :ref:`asynch-deletes`
+- :ref:`one-entry-ring`
+- :ref:`can-large-blob`
+- :ref:`nodetool-connection-refused`
+- :ref:`to-batch-or-not-to-batch`
+- :ref:`selinux`
+- :ref:`how-to-unsubscribe`
+- :ref:`cassandra-eats-all-my-memory`
+- :ref:`what-are-seeds`
+- :ref:`are-seeds-SPOF`
+- :ref:`why-message-dropped`
+- :ref:`oom-map-failed`
+- :ref:`what-on-same-timestamp-update`
+- :ref:`why-bootstrapping-stream-error`
+
+.. _why-cant-list-all:
+
+Why can't I set ``listen_address`` to listen on 0.0.0.0 (all my addresses)?
+---------------------------------------------------------------------------
+
+Cassandra is a gossip-based distributed system and ``listen_address`` is the address a node tells other nodes to reach
+it at. Telling other nodes "contact me on any of my addresses" is a bad idea; if different nodes in the cluster pick
+different addresses for you, Bad Things happen.
+
+If you don't want to manually specify an IP to ``listen_address`` for each node in your cluster (understandable!), leave
+it blank and Cassandra will use ``InetAddress.getLocalHost()`` to pick an address. Then it's up to you or your ops team
+to make things resolve correctly (``/etc/hosts/``, dns, etc).
+
+One exception to this process is JMX, which by default binds to 0.0.0.0 (Java bug 6425769).
+
+See :jira:`256` and :jira:`43` for more gory details.
+
+.. _what-ports:
+
+What ports does Cassandra use?
+------------------------------
+
+By default, Cassandra uses 7000 for cluster communication (7001 if SSL is enabled), 9042 for native protocol clients,
+and 7199 for JMX (and 9160 for the deprecated Thrift interface). The internode communication and native protocol ports
+are configurable in the :ref:`cassandra-yaml`. The JMX port is configurable in ``cassandra-env.sh`` (through JVM
+options). All ports are TCP.
+
+.. _what-happens-on-joins:
+
+What happens to existing data in my cluster when I add new nodes?
+-----------------------------------------------------------------
+
+When a new nodes joins a cluster, it will automatically contact the other nodes in the cluster and copy the right data
+to itself. See :ref:`topology-changes`.
+
+.. _asynch-deletes:
+
+I delete data from Cassandra, but disk usage stays the same. What gives?
+------------------------------------------------------------------------
+
+Data you write to Cassandra gets persisted to SSTables. Since SSTables are immutable, the data can't actually be removed
+when you perform a delete, instead, a marker (also called a "tombstone") is written to indicate the value's new status.
+Never fear though, on the first compaction that occurs between the data and the tombstone, the data will be expunged
+completely and the corresponding disk space recovered. See :ref:`compaction` for more detail.
+
+.. _one-entry-ring:
+
+Why does nodetool ring only show one entry, even though my nodes logged that they see each other joining the ring?
+------------------------------------------------------------------------------------------------------------------
+
+This happens when you have the same token assigned to each node. Don't do that.
+
+Most often this bites people who deploy by installing Cassandra on a VM (especially when using the Debian package, which
+auto-starts Cassandra after installation, thus generating and saving a token), then cloning that VM to other nodes.
+
+The easiest fix is to wipe the data and commitlog directories, thus making sure that each node will generate a random
+token on the next restart.
+
+.. _change-replication-factor:
+
+Can I change the replication factor (a a keyspace) on a live cluster?
+---------------------------------------------------------------------
+
+Yes, but it will require running repair (or cleanup) to change the replica count of existing data:
+
+- :ref:`Alter <alter-keyspace-statement>` the replication factor for desired keyspace (using cqlsh for instance).
+- If you're reducing the replication factor, run ``nodetool cleanup`` on the cluster to remove surplus replicated data.
+ Cleanup runs on a per-node basis.
+- If you're increasing the replication factor, run ``nodetool repair`` to ensure data is replicated according to the new
+ configuration. Repair runs on a per-replica set basis. This is an intensive process that may result in adverse cluster
+ performance. It's highly recommended to do rolling repairs, as an attempt to repair the entire cluster at once will
+ most likely swamp it.
+
+.. _can-large-blob:
+
+Can I Store (large) BLOBs in Cassandra?
+---------------------------------------
+
+Cassandra isn't optimized for large file or BLOB storage and a single ``blob`` value is always read and send to the
+client entirely. As such, storing small blobs (less than single digit MB) should not be a problem, but it is advised to
+manually split large blobs into smaller chunks.
+
+Please note in particular that by default, any value greater than 16MB will be rejected by Cassandra due the
+``max_mutation_size_in_kb`` configuration of the :ref:`cassandra-yaml` file (which default to half of
+``commitlog_segment_size_in_mb``, which itself default to 32MB).
+
+.. _nodetool-connection-refused:
+
+Nodetool says "Connection refused to host: 127.0.1.1" for any remote host. What gives?
+--------------------------------------------------------------------------------------
+
+Nodetool relies on JMX, which in turn relies on RMI, which in turn sets up its own listeners and connectors as needed on
+each end of the exchange. Normally all of this happens behind the scenes transparently, but incorrect name resolution
+for either the host connecting, or the one being connected to, can result in crossed wires and confusing exceptions.
+
+If you are not using DNS, then make sure that your ``/etc/hosts`` files are accurate on both ends. If that fails, try
+setting the ``-Djava.rmi.server.hostname=<public name>`` JVM option near the bottom of ``cassandra-env.sh`` to an
+interface that you can reach from the remote machine.
+
+.. _to-batch-or-not-to-batch:
+
+Will batching my operations speed up my bulk load?
+--------------------------------------------------
+
+No. Using batches to load data will generally just add "spikes" of latency. Use asynchronous INSERTs instead, or use
+true :ref:`bulk-loading`.
+
+An exception is batching updates to a single partition, which can be a Good Thing (as long as the size of a single batch
+stay reasonable). But never ever blindly batch everything!
+
+.. _selinux:
+
+On RHEL nodes are unable to join the ring
+-----------------------------------------
+
+Check if `SELinux <https://en.wikipedia.org/wiki/Security-Enhanced_Linux>`__ is on; if it is, turn it off.
+
+.. _how-to-unsubscribe:
+
+How do I unsubscribe from the email list?
+-----------------------------------------
+
+Send an email to ``user-unsubscribe@cassandra.apache.org``.
+
+.. _cassandra-eats-all-my-memory:
+
+Why does top report that Cassandra is using a lot more memory than the Java heap max?
+-------------------------------------------------------------------------------------
+
+Cassandra uses `Memory Mapped Files <https://en.wikipedia.org/wiki/Memory-mapped_file>`__ (mmap) internally. That is, we
+use the operating system's virtual memory system to map a number of on-disk files into the Cassandra process' address
+space. This will "use" virtual memory; i.e. address space, and will be reported by tools like top accordingly, but on 64
+bit systems virtual address space is effectively unlimited so you should not worry about that.
+
+What matters from the perspective of "memory use" in the sense as it is normally meant, is the amount of data allocated
+on brk() or mmap'd /dev/zero, which represent real memory used. The key issue is that for a mmap'd file, there is never
+a need to retain the data resident in physical memory. Thus, whatever you do keep resident in physical memory is
+essentially just there as a cache, in the same way as normal I/O will cause the kernel page cache to retain data that
+you read/write.
+
+The difference between normal I/O and mmap() is that in the mmap() case the memory is actually mapped to the process,
+thus affecting the virtual size as reported by top. The main argument for using mmap() instead of standard I/O is the
+fact that reading entails just touching memory - in the case of the memory being resident, you just read it - you don't
+even take a page fault (so no overhead in entering the kernel and doing a semi-context switch). This is covered in more
+detail `here <http://www.varnish-cache.org/trac/wiki/ArchitectNotes>`__.
+
+.. _what-are-seeds:
+
+What are seeds?
+---------------
+
+Seeds are used during startup to discover the cluster.
+
+If you configure your nodes to refer some node as seed, nodes in your ring tend to send Gossip message to seeds more
+often (also see the :ref:`section on gossip <gossip>`) than to non-seeds. In other words, seeds are worked as hubs of
+Gossip network. With seeds, each node can detect status changes of other nodes quickly.
+
+Seeds are also referred by new nodes on bootstrap to learn other nodes in ring. When you add a new node to ring, you
+need to specify at least one live seed to contact. Once a node join the ring, it learns about the other nodes, so it
+doesn't need seed on subsequent boot.
+
+You can make a seed a node at any time. There is nothing special about seed nodes. If you list the node in seed list it
+is a seed
+
+Seeds do not auto bootstrap (i.e. if a node has itself in its seed list it will not automatically transfer data to itself)
+If you want a node to do that, bootstrap it first and then add it to seeds later. If you have no data (new install) you
+do not have to worry about bootstrap at all.
+
+Recommended usage of seeds:
+
+- pick two (or more) nodes per data center as seed nodes.
+- sync the seed list to all your nodes
+
+.. _are-seeds-SPOF:
+
+Does single seed mean single point of failure?
+----------------------------------------------
+
+The ring can operate or boot without a seed; however, you will not be able to add new nodes to the cluster. It is
+recommended to configure multiple seeds in production system.
+
+.. _cant-call-jmx-method:
+
+Why can't I call jmx method X on jconsole?
+------------------------------------------
+
+Some of JMX operations use array argument and as jconsole doesn't support array argument, those operations can't be
+called with jconsole (the buttons are inactive for them). You need to write a JMX client to call such operations or need
+array-capable JMX monitoring tool.
+
+.. _why-message-dropped:
+
+Why do I see "... messages dropped ..." in the logs?
+----------------------------------------------------
+
+This is a symptom of load shedding -- Cassandra defending itself against more requests than it can handle.
+
+Internode messages which are received by a node, but do not get not to be processed within their proper timeout (see
+``read_request_timeout``, ``write_request_timeout``, ... in the :ref:`cassandra-yaml`), are dropped rather than
+processed (since the as the coordinator node will no longer be waiting for a response).
+
+For writes, this means that the mutation was not applied to all replicas it was sent to. The inconsistency will be
+repaired by read repair, hints or a manual repair. The write operation may also have timeouted as a result.
+
+For reads, this means a read request may not have completed.
+
+Load shedding is part of the Cassandra architecture, if this is a persistent issue it is generally a sign of an
+overloaded node or cluster.
+
+.. _oom-map-failed:
+
+Cassandra dies with ``java.lang.OutOfMemoryError: Map failed``
+--------------------------------------------------------------
+
+If Cassandra is dying **specifically** with the "Map failed" message, it means the OS is denying java the ability to
+lock more memory. In linux, this typically means memlock is limited. Check ``/proc/<pid of cassandra>/limits`` to verify
+this and raise it (eg, via ulimit in bash). You may also need to increase ``vm.max_map_count.`` Note that the debian
+package handles this for you automatically.
+
+
+.. _what-on-same-timestamp-update:
+
+What happens if two updates are made with the same timestamp?
+-------------------------------------------------------------
+
+Updates must be commutative, since they may arrive in different orders on different replicas. As long as Cassandra has a
+deterministic way to pick the winner (in a timestamp tie), the one selected is as valid as any other, and the specifics
+should be treated as an implementation detail. That said, in the case of a timestamp tie, Cassandra follows two rules:
+first, deletes take precedence over inserts/updates. Second, if there are two updates, the one with the lexically larger
+value is selected.
+
+.. _why-bootstrapping-stream-error:
+
+Why bootstrapping a new node fails with a "Stream failed" error?
+----------------------------------------------------------------
+
+Two main possibilities:
+
+#. the GC may be creating long pauses disrupting the streaming process
+#. compactions happening in the background hold streaming long enough that the TCP connection fails
+
+In the first case, regular GC tuning advices apply. In the second case, you need to set TCP keepalive to a lower value
+(default is very high on Linux). Try to just run the following::
+
+ $ sudo /sbin/sysctl -w net.ipv4.tcp_keepalive_time=60 net.ipv4.tcp_keepalive_intvl=60 net.ipv4.tcp_keepalive_probes=5
+
+To make those settings permanent, add them to your ``/etc/sysctl.conf`` file.
+
+Note: `GCE <https://cloud.google.com/compute/>`__'s firewall will always interrupt TCP connections that are inactive for
+more than 10 min. Running the above command is highly recommended in that environment.
+
+
+
+
+
+
+
+
+
+
+
Added: cassandra/site/src/doc/3.10/_sources/getting_started/configuring.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/getting_started/configuring.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/getting_started/configuring.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/getting_started/configuring.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,67 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Configuring Cassandra
+---------------------
+
+For running Cassandra on a single node, the steps above are enough, you don't really need to change any configuration.
+However, when you deploy a cluster of nodes, or use clients that are not on the same host, then there are some
+parameters that must be changed.
+
+The Cassandra configuration files can be found in the ``conf`` directory of tarballs. For packages, the configuration
+files will be located in ``/etc/cassandra``.
+
+Main runtime properties
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Most of configuration in Cassandra is done via yaml properties that can be set in ``cassandra.yaml``. At a minimum you
+should consider setting the following properties:
+
+- ``cluster_name``: the name of your cluster.
+- ``seeds``: a comma separated list of the IP addresses of your cluster seeds.
+- ``storage_port``: you don't necessarily need to change this but make sure that there are no firewalls blocking this
+ port.
+- ``listen_address``: the IP address of your node, this is what allows other nodes to communicate with this node so it
+ is important that you change it. Alternatively, you can set ``listen_interface`` to tell Cassandra which interface to
+ use, and consecutively which address to use. Set only one, not both.
+- ``native_transport_port``: as for storage\_port, make sure this port is not blocked by firewalls as clients will
+ communicate with Cassandra on this port.
+
+Changing the location of directories
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following yaml properties control the location of directories:
+
+- ``data_file_directories``: one or more directories where data files are located.
+- ``commitlog_directory``: the directory where commitlog files are located.
+- ``saved_caches_directory``: the directory where saved caches are located.
+- ``hints_directory``: the directory where hints are located.
+
+For performance reasons, if you have multiple disks, consider putting commitlog and data files on different disks.
+
+Environment variables
+^^^^^^^^^^^^^^^^^^^^^
+
+JVM-level settings such as heap size can be set in ``cassandra-env.sh``. You can add any additional JVM command line
+argument to the ``JVM_OPTS`` environment variable; when Cassandra starts these arguments will be passed to the JVM.
+
+Logging
+^^^^^^^
+
+The logger in use is logback. You can change logging properties by editing ``logback.xml``. By default it will log at
+INFO level into a file called ``system.log`` and at debug level into a file called ``debug.log``. When running in the
+foreground, it will also log at INFO level to the console.
+
Added: cassandra/site/src/doc/3.10/_sources/getting_started/drivers.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/getting_started/drivers.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/getting_started/drivers.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/getting_started/drivers.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,107 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. _client-drivers:
+
+Client drivers
+--------------
+
+Here are known Cassandra client drivers organized by language. Before choosing a driver, you should verify the Cassandra
+version and functionality supported by a specific driver.
+
+Java
+^^^^
+
+- `Achilles <http://achilles.archinnov.info/>`__
+- `Astyanax <https://github.com/Netflix/astyanax/wiki/Getting-Started>`__
+- `Casser <https://github.com/noorq/casser>`__
+- `Datastax Java driver <https://github.com/datastax/java-driver>`__
+- `Kundera <https://github.com/impetus-opensource/Kundera>`__
+- `PlayORM <https://github.com/deanhiller/playorm>`__
+
+Python
+^^^^^^
+
+- `Datastax Python driver <https://github.com/datastax/python-driver>`__
+
+Ruby
+^^^^
+
+- `Datastax Ruby driver <https://github.com/datastax/ruby-driver>`__
+
+C# / .NET
+^^^^^^^^^
+
+- `Cassandra Sharp <https://github.com/pchalamet/cassandra-sharp>`__
+- `Datastax C# driver <https://github.com/datastax/csharp-driver>`__
+- `Fluent Cassandra <https://github.com/managedfusion/fluentcassandra>`__
+
+Nodejs
+^^^^^^
+
+- `Datastax Nodejs driver <https://github.com/datastax/nodejs-driver>`__
+- `Node-Cassandra-CQL <https://github.com/jorgebay/node-cassandra-cql>`__
+
+PHP
+^^^
+
+- `CQL \| PHP <http://code.google.com/a/apache-extras.org/p/cassandra-pdo>`__
+- `Datastax PHP driver <https://github.com/datastax/php-driver/>`__
+- `PHP-Cassandra <https://github.com/aparkhomenko/php-cassandra>`__
+- `PHP Library for Cassandra <http://evseevnn.github.io/php-cassandra-binary/>`__
+
+C++
+^^^
+
+- `Datastax C++ driver <https://github.com/datastax/cpp-driver>`__
+- `libQTCassandra <http://sourceforge.net/projects/libqtcassandra>`__
+
+Scala
+^^^^^
+
+- `Datastax Spark connector <https://github.com/datastax/spark-cassandra-connector>`__
+- `Phantom <https://github.com/newzly/phantom>`__
+- `Quill <https://github.com/getquill/quill>`__
+
+Clojure
+^^^^^^^
+
+- `Alia <https://github.com/mpenet/alia>`__
+- `Cassaforte <https://github.com/clojurewerkz/cassaforte>`__
+- `Hayt <https://github.com/mpenet/hayt>`__
+
+Erlang
+^^^^^^
+
+- `CQerl <https://github.com/matehat/cqerl>`__
+- `Erlcass <https://github.com/silviucpp/erlcass>`__
+
+Go
+^^
+
+- `CQLc <http://relops.com/cqlc/>`__
+- `Gocassa <https://github.com/hailocab/gocassa>`__
+- `GoCQL <https://github.com/gocql/gocql>`__
+
+Haskell
+^^^^^^^
+
+- `Cassy <https://github.com/ozataman/cassy>`__
+
+Rust
+^^^^
+
+- `Rust CQL <https://github.com/neich/rust-cql>`__
Added: cassandra/site/src/doc/3.10/_sources/getting_started/index.txt
URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/_sources/getting_started/index.txt?rev=1757419&view=auto
==============================================================================
--- cassandra/site/src/doc/3.10/_sources/getting_started/index.txt (added)
+++ cassandra/site/src/doc/3.10/_sources/getting_started/index.txt Tue Aug 23 19:25:17 2016
@@ -0,0 +1,33 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Getting Started
+===============
+
+This section covers how to get started using Apache Cassandra and should be the first thing to read if you are new to
+Cassandra.
+
+.. toctree::
+ :maxdepth: 2
+
+ installing
+ configuring
+ querying
+ drivers
+
+