You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by sp...@apache.org on 2017/03/28 17:14:24 UTC
cassandra git commit: Docs: add "Documentation contributors guide"
Repository: cassandra
Updated Branches:
refs/heads/trunk 91c5f4c28 -> 0a091fcec
Docs: add "Documentation contributors guide"
patch by Stefan Podkowinski; reviewed by Jeff Jirsa for CASSANDRA-13256
Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo
Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/0a091fce
Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/0a091fce
Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/0a091fce
Branch: refs/heads/trunk
Commit: 0a091fceccaac003a2e5449591546d712b6fed8e
Parents: 91c5f4c
Author: Stefan Podkowinski <s....@gmail.com>
Authored: Tue Mar 14 21:56:38 2017 +0100
Committer: Stefan Podkowinski <s....@gmail.com>
Committed: Tue Mar 28 19:03:30 2017 +0200
----------------------------------------------------------------------
doc/source/development/documentation.rst | 104 +++++++++++++++++++
doc/source/development/images/docs_commit.png | Bin 0 -> 104667 bytes
.../development/images/docs_create_branch.png | Bin 0 -> 181860 bytes
.../development/images/docs_create_file.png | Bin 0 -> 209110 bytes
doc/source/development/images/docs_editor.png | Bin 0 -> 106175 bytes
doc/source/development/images/docs_fork.png | Bin 0 -> 76159 bytes
doc/source/development/images/docs_pr.png | Bin 0 -> 156081 bytes
doc/source/development/images/docs_preview.png | Bin 0 -> 123826 bytes
doc/source/development/index.rst | 1 +
9 files changed, 105 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/documentation.rst
----------------------------------------------------------------------
diff --git a/doc/source/development/documentation.rst b/doc/source/development/documentation.rst
new file mode 100644
index 0000000..8b7cd4e
--- /dev/null
+++ b/doc/source/development/documentation.rst
@@ -0,0 +1,104 @@
+.. 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.
+
+
+Working on Documentation
+*************************
+
+How Cassandra is documented
+===========================
+
+The official Cassandra documentation lives in the project's git repository. We use a static site generator, `Sphinx <http://www.sphinx-doc.org/>`_, to create pages hosted at `cassandra.apache.org <https://cassandra.apache.org/doc/latest/>`_. You'll also find developer centric content about Cassandra internals in our retired `wiki <https://wiki.apache.org/cassandra>`_ (not covered by this guide).
+
+Using a static site generator often requires to use a markup language instead of visual editors (which some people would call good news). Sphinx, the tool-set we use to generate our documentation, uses `reStructuredText <http://www.sphinx-doc.org/en/stable/rest.html>`_ for that. Markup languages allow you to format text by making use of certain syntax elements. Your document structure will also have to follow specific conventions. Feel free to take a look at `existing documents <..>`_ to get a better idea how we use reStructuredText to write our documents.
+
+So how do you actually start making contributions?
+
+GitHub based work flow
+======================
+
+*Recommended for shorter documents and minor changes on existing content (e.g. fixing typos or updating descriptions)*
+
+Follow these steps to contribute using GitHub. It's assumed that you're logged in with an existing account.
+
+1. Fork the GitHub mirror of the `Cassandra repository <https://github.com/apache/cassandra>`_
+
+.. image:: images/docs_fork.png
+
+2. Create a new branch that you can use to make your edits. It's recommended to have a separate branch for each of your working projects. It will also make it easier to create a pull request later to when you decide you\u2019re ready to contribute your work.
+
+.. image:: images/docs_create_branch.png
+
+3. Navigate to document sources ``doc/source`` to find the ``.rst`` file to edit. The URL of the document should correspond to the directory structure. New files can be created using the "Create new file" button:
+
+.. image:: images/docs_create_file.png
+
+4. At this point you should be able to edit the file using the GitHub web editor. Start by naming your file and add some content. Have a look at other existing ``.rst`` files to get a better idea what format elements to use.
+
+.. image:: images/docs_editor.png
+
+Make sure to preview added content before committing any changes.
+
+.. image:: images/docs_preview.png
+
+5. Commit your work when you're done. Make sure to add a short description of all your edits since the last time you committed before.
+
+.. image:: images/docs_commit.png
+
+6. Finally if you decide that you're done working on your branch, it's time to create a pull request!
+
+.. image:: images/docs_pr.png
+
+Afterwards the GitHub Cassandra mirror will list your pull request and you're done. Congratulations! Please give us some time to look at your suggested changes before we get back to you.
+
+
+Jira based work flow
+====================
+
+*Recommended for major changes*
+
+Significant changes to the documentation are best managed through our Jira issue tracker. Please follow the same `contribution guides <https://cassandra.apache.org/doc/latest/development/patches.html>`_ as for regular code contributions. Creating high quality content takes a lot of effort. It\u2019s therefor always a good idea to create a ticket before you start and explain what you\u2019re planing to do. This will create the opportunity for other contributors and committers to comment on your ideas and work so far. Eventually your patch gets a formal review before it is committed.
+
+Working on documents locally using Sphinx
+=========================================
+
+*Recommended for advanced editing*
+
+Using the GitHub web interface should allow you to use most common layout elements including images. More advanced formatting options and navigation elements depend on Sphinx to render correctly. Therefor it\u2019s a good idea to setup Sphinx locally for any serious editing. Please follow the instructions in the Cassandra source directory at ``doc/README.md``. Setup is very easy (at least on OSX and Linux).
+
+Notes for committers
+====================
+
+Please feel free to get involved and merge pull requests created on the GitHub mirror if you're a committer. As this is a read-only repository, you won't be able to merge a PR directly on GitHub. You'll have to commit the changes against the Apache repository with a comment that will close the PR when the committ syncs with GitHub.
+
+You may use a git work flow like this::
+
+ git remote add github https://github.com/apache/cassandra.git
+ git fetch github pull/<PR-ID>/head:<PR-ID>
+ git checkout <PR-ID>
+
+Now either rebase or squash the commit, e.g. for squashing::
+
+ git reset --soft origin/trunk
+ git commit --author <PR Author>
+
+Make sure to add a proper commit message including a "Closes #<PR-ID>" text to automatically close the PR.
+
+Publishing
+----------
+
+Details for building and publishing of the site at cassandra.apache.org can be found `here <https://svn.apache.org/repos/asf/cassandra/site/src/README>`_.
+
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/images/docs_commit.png
----------------------------------------------------------------------
diff --git a/doc/source/development/images/docs_commit.png b/doc/source/development/images/docs_commit.png
new file mode 100644
index 0000000..d90d96a
Binary files /dev/null and b/doc/source/development/images/docs_commit.png differ
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/images/docs_create_branch.png
----------------------------------------------------------------------
diff --git a/doc/source/development/images/docs_create_branch.png b/doc/source/development/images/docs_create_branch.png
new file mode 100644
index 0000000..a04cb54
Binary files /dev/null and b/doc/source/development/images/docs_create_branch.png differ
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/images/docs_create_file.png
----------------------------------------------------------------------
diff --git a/doc/source/development/images/docs_create_file.png b/doc/source/development/images/docs_create_file.png
new file mode 100644
index 0000000..b51e370
Binary files /dev/null and b/doc/source/development/images/docs_create_file.png differ
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/images/docs_editor.png
----------------------------------------------------------------------
diff --git a/doc/source/development/images/docs_editor.png b/doc/source/development/images/docs_editor.png
new file mode 100644
index 0000000..5b9997b
Binary files /dev/null and b/doc/source/development/images/docs_editor.png differ
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/images/docs_fork.png
----------------------------------------------------------------------
diff --git a/doc/source/development/images/docs_fork.png b/doc/source/development/images/docs_fork.png
new file mode 100644
index 0000000..20a592a
Binary files /dev/null and b/doc/source/development/images/docs_fork.png differ
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/images/docs_pr.png
----------------------------------------------------------------------
diff --git a/doc/source/development/images/docs_pr.png b/doc/source/development/images/docs_pr.png
new file mode 100644
index 0000000..211eb25
Binary files /dev/null and b/doc/source/development/images/docs_pr.png differ
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/images/docs_preview.png
----------------------------------------------------------------------
diff --git a/doc/source/development/images/docs_preview.png b/doc/source/development/images/docs_preview.png
new file mode 100644
index 0000000..207f0ac
Binary files /dev/null and b/doc/source/development/images/docs_preview.png differ
http://git-wip-us.apache.org/repos/asf/cassandra/blob/0a091fce/doc/source/development/index.rst
----------------------------------------------------------------------
diff --git a/doc/source/development/index.rst b/doc/source/development/index.rst
index b2169e4..a09c945 100644
--- a/doc/source/development/index.rst
+++ b/doc/source/development/index.rst
@@ -27,3 +27,4 @@ Contributing to Cassandra
code_style
how_to_review
how_to_commit
+ documentation