Update hacking.rst with copyright info and other hints. GH #331

[ci skip]

1 files changed, 78 insertions, 7 deletions

diff --git a/doc/hacking.rst b/doc/hacking.rst
index 3196faa0a..41ec9ca01 100644
--- a/doc/hacking.rst
+++ b/doc/hacking.rst
@@ -13,7 +13,7 @@ Under `src` there are directories
   example `build-data/cc/gcc.txt` describes various gcc options.
 * `scripts` contains various scripts: install, distribution, various
   codegen things. Scripts controlling CI go under `scripts/ci`.
-* `python` and `ocaml` are the FFI bindings for those languages
+* `python/botan.py` is the Python ctypes wrapper
 
 Library Layout
 ========================================
@@ -49,16 +49,50 @@ Library Layout
 * `ffi` is the C99 API
 * `vendor` contains bindings to external libraries like OpenSSL and Sqlite3
 
+Copyright Notice
+========================================
+
+At the top of any new file add a comment with a copyright and
+a reference to the license, for examplee::
+
+  /*
+  * (C) 2015,2016 Copyright Holder
+  * Botan is released under the Simplified BSD License (see license.txt)
+  */
+
+If you are making a substantial or non-trivial change to an existing
+file, add or update your own copyright statement at the top of the
+file.  If you are making a change in a new year not covered by your
+existing statement, add the year. Even if the years you are making the
+change are consecutive, avoid year ranges: specify each year separated
+by a comma.
+
+Also if you are a new contributor or making an addition in a new year,
+include an update to `doc/license.txt` in your PR.
+
 Style Conventions
 ========================================
 
 When writing your code remember the need for it to be easily
-understood by reviewers/auditors, both at the time of the patch
+understood by reviewers and auditors, both at the time of the patch
 submission and in the future.
 
 Avoid complicated template metaprogramming where possible. It has its
 places but should be used judiciously.
 
+When designing a new API (for use either by library users or just
+internally) try writing out the calling code first. That is, write out
+some code calling your idealized API, then just implement that. This
+can often help avoid cut-and-paste by creating the correct abstractions
+needed to solve the problem at hand.
+
+The C++11 `auto` keyword is very convenient but only use it when the
+type truly is obvious (considering also the potential for unexpected
+integer conversions and the like, such as an apparent uint8_t being
+promoted to an int).
+
+Use `override` annotations whenever possible.
+
 A formatting setup for emacs is included in `scripts/indent.el` but
 the basic formatting style should be obvious. No tabs, and remove
 trailing whitespace.
@@ -73,14 +107,51 @@ this.
 Sending patches
 ========================================
 
-All contributions should be submitted as pull requests via the github page.
-If you are planning a large change email the mailing list or open a
-discussion ticket on github before starting out.
+All contributions should be submitted as pull requests via GitHub
+(https://github.com/randombit/botan). If you are planning a large
+change email the mailing list or open a discussion ticket on github
+before starting out to make sure you are on the right path to
+something which we'll be able to accept.
+
+Depending on what your change is, your PR should probably also include
+an update to `doc/news.rst` with a note explaining the change. If your
+change is a simple bug fix, a one sentence description is perhaps
+sufficient. If there is an existing ticket on GitHub with discussion
+or other information, reference it in your change note as 'GH #000'.
+
+Update `doc/credits.txt` with your information so people know what
+you did! (This is optional)
 
 If you are interested in contributing but don't know where to start
-check out todo.rst for some ideas - these are projects we would almost
-certainly accept if the code quality was high.
+check out `doc/todo.rst` for some ideas - these are changes we would
+almost certainly accept once they've passed code review.
 
 Also, try building and testing it on whatever hardware you have handy,
 especially non-x86 platforms, or especially C++11 compilers other
 than the regularly tested GCC, Clang, and Visual Studio compilers.
+
+Build Tools and Hints
+========================================
+
+If you don't already use it for all your C/C++ development, install
+`ccache` now and configure a large cache on a fast disk. It allows for
+very quick rebuilds by caching the compiler output.
+
+Use `--with-sanitizers` to enable ASan. UBSan has to be added separately
+with --cc-abi-flags at the moment as GCC 4.8 does not have UBSan.
+
+Other Ways You Can Help
+========================================
+
+Convince your employer that the software your company uses and relies on is
+worth the time and cost of serious audit. The code may be free, but you are
+still using it - so make sure it is any good. Fund code and design reviews
+whenever you can of the free software your company relies on, including Botan,
+then share the results with the developers to improve the ecosystem for everyone.
+
+Funding Development
+========================================
+
+If there is a change you'd like implemented in the library but you'd rather not,
+or can't, write it yourself, you can contact Jack Lloyd who in addition to being
+the primary author also works as a freelance contractor and security consultant.