From ef1c5e3a7ebc26f980643a96d795a4cc0ac5a5ec Mon Sep 17 00:00:00 2001
From: "C. Titus Brown" <titus@idyll.org>
Date: Tue, 22 Jul 2014 08:02:07 -0400
Subject: [PATCH] more updates

---
 doc/dev/codebase-guide.txt               | 14 +++++
 doc/dev/coding-guidelines-and-review.txt | 73 ++++++++++++++++++++++++
 doc/dev/getting-started.txt              |  8 +++
 3 files changed, 95 insertions(+)
 create mode 100644 doc/dev/codebase-guide.txt
 create mode 100644 doc/dev/coding-guidelines-and-review.txt

diff --git a/doc/dev/codebase-guide.txt b/doc/dev/codebase-guide.txt
new file mode 100644
index 0000000000..fe6d2c5065
--- /dev/null
+++ b/doc/dev/codebase-guide.txt
@@ -0,0 +1,14 @@
+A quick guide to the khmer codebase
+===================================
+
+The ChangeLog file lists changes to the codebase, most recent first.
+
+The lib/ directory contains all of the C++ code.
+
+The khmer/ directory contains the khmer package (khmer/khmer/__init__.py etc)
+and the C++-to-Python bridge (khmer/_khmermodule.cc).
+
+The scripts/ and sandbox/ directory contain command-line scripts.
+
+The tests/ directory contains all of the tests.
+
diff --git a/doc/dev/coding-guidelines-and-review.txt b/doc/dev/coding-guidelines-and-review.txt
new file mode 100644
index 0000000000..66e254d96f
--- /dev/null
+++ b/doc/dev/coding-guidelines-and-review.txt
@@ -0,0 +1,73 @@
+Coding guidelines and code review checklist
+===========================================
+
+(Copied from :doc:`../development.txt`)
+
+Coding standards
+----------------
+
+All plain-text files should have line widths of 80 characters or less unless
+that is not supported for the particular file format.
+
+For C++, we use `Todd Hoff's coding standard
+<http://www.possibility.com/Cpp/CppCodingStandard.html>`__, and
+`astyle -A10 / "One True Brace Style"
+<http://astyle.sourceforge.net/astyle.html>`__ indentation and
+bracing.  Note: @CTB needs emacs settings that work for this.
+
+Vim users may want to set the ARTISTIC_STYLE_OPTIONS shell variable to "-A10
+--max-code-length=80" and run ```:%!astyle``` to reformat. The four space
+indentation can be set with::
+
+	set expandtab
+	set shiftwidth=4
+	set softtabstop=4
+
+For Python, `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`__ is our
+standard. The ```pep8``` and ```autopep8``` Makefile targets are helpful. 
+
+Code, scripts, and documentation must have its spelling checked. Vim users can
+run::
+
+        :setlocal spell spelllang=en_us
+
+Use `]s` and `[s` to navigate between misspellings and `z=` to suggest a
+correctly spelled word. `zg` will add a word as a good word.
+
+GNU's `aspell` can also be used to check the spelling in a single file::
+
+        aspell check --mode ccpp $filename
+
+Code Review
+-----------
+
+Please read `11 Best Practices for Peer Code Review
+<http://smartbear.com/SmartBear/media/pdfs/WP-CC-11-Best-Practices-of-Peer-Code-Review.pdf>`__.
+
+See also `Code reviews: the lab meeting for code
+<http://fperez.org/py4science/code_reviews.html>`__ and
+`the PyCogent coding guidelines
+<http://pycogent.org/coding_guidelines.html>`__.
+
+Checklist
+---------
+
+Copy and paste the following into a pull-request when it is ready for review::
+   
+   - [ ] Is it mergable
+   - [ ] Did it pass the tests?
+   - [ ] If it introduces new functionality in scripts/ is it tested?
+     Check for code coverage.
+   - [ ] Is it well formatted? Look at `pep8`/`pylint`, `cppcheck`, and
+     `make doc` output. Use `autopep8` and `astyle -A10 --max-code-length=80`
+     if needed. 
+   - [ ] Is it documented in the Changelog?
+   - [ ] Was spellcheck run on the source code and documentation after changes
+     were made?
+
+Testing
+-------
+
+``./setup.py nosetest`` is the canonical way to run the tests.  This is what
+``make test`` does.
+
diff --git a/doc/dev/getting-started.txt b/doc/dev/getting-started.txt
index 9e903e16fb..5fc1742e6e 100644
--- a/doc/dev/getting-started.txt
+++ b/doc/dev/getting-started.txt
@@ -5,6 +5,12 @@ Start by making your own copy of khmer and setting yourself up for
 development; then, build khmer and run the tests; and finally, claim
 an issue and start developing!
 
+If you're unfamiliar with git and branching in particular, check out
+the `git-scm book <http://git-scm.com/book/en/Git-Branching>`__.
+
+We've provided a quick guide to the khmer code base here:
+:doc:`codebase-guide`.
+
 One-time Preparation
 --------------------
 
@@ -127,6 +133,8 @@ Claiming an issue and starting to develop
 
    This will be issue dependent ;).
 
+   You will need to visit and revisit :doc:`coding-guidelines-and-review`.
+
 #. Run the tests and/or build the docs _after_ your changes have been committed::
 
       make doc test