3 files changed, 67 insertions, 15 deletions
diff --git a/doc/HACKING/HowToReview.md b/doc/HACKING/HowToReview.md
index 2d1f3d1c9e..2325e70175 100644
--- a/doc/HACKING/HowToReview.md
+++ b/doc/HACKING/HowToReview.md
@@ -63,7 +63,7 @@ Let's look at the code!
 Let's look at the documentation!
 --------------------------------
 
-- Does the documentation confirm to CodingStandards.txt?
+- Does the documentation conform to CodingStandards.txt?
 
 - Does it make sense?
 
diff --git a/doc/HACKING/Module.md b/doc/HACKING/Module.md
index 9cf36090b4..3a07d0c639 100644
--- a/doc/HACKING/Module.md
+++ b/doc/HACKING/Module.md
@@ -8,13 +8,18 @@ module in Tor.
 In the context of the tor code base, a module is a subsystem that we can
 selectively enable or disable, at `configure` time.
 
-Currently, there is only one module:
+Currently, tor has these modules:
 
+  - Relay subsystem (relay)
   - Directory Authority subsystem (dirauth)
 
-It is located in its own directory in `src/feature/dirauth/`. To disable it,
-one need to pass `--disable-module-dirauth` at configure time. All modules
-are currently enabled by default.
+dirauth is located in its own directory in `src/feature/dirauth/`.
+
+Relay is located in directories named `src/*/*relay` and `src/*/*dircache`,
+which are being progressively refactored and disabled.
+
+To disable a module, pass `--disable-module-{dirauth,relay}` at configure
+time. All modules are currently enabled by default.
 
 ## Build System ##
 
@@ -24,7 +29,7 @@ The changes to the build system are pretty straightforward.
    contains a list (white-space separated) of the module in tor. Add yours to
    the list.
 
-2. Use the `AC_ARG_ENABLE([module-dirauth]` template for your new module. We
+2. Use the `AC_ARG_ENABLE([module-relay]` template for your new module. We
    use the "disable module" approach instead of enabling them one by one. So,
    by default, tor will build all the modules.
 
@@ -32,7 +37,7 @@ The changes to the build system are pretty straightforward.
    the C code to conditionally compile things for your module. And the
    `BUILD_MODULE_<name>` is also defined for automake files (e.g: include.am).
 
-3. In the `src/core/include.am` file, locate the `MODULE_DIRAUTH_SOURCES`
+3. In the `src/core/include.am` file, locate the `MODULE_RELAY_SOURCES`
    value.  You need to create your own `_SOURCES` variable for your module
    and then conditionally add the it to `LIBTOR_A_SOURCES` if you should
    build the module.
@@ -40,18 +45,14 @@ The changes to the build system are pretty straightforward.
    It is then **very** important to add your SOURCES variable to
    `src_or_libtor_testing_a_SOURCES` so the tests can build it.
 
-4. Do the same for header files, locate `ORHEADERS +=` which always add all
-   headers of all modules so the symbol can be found for the module entry
-   points.
-
 Finally, your module will automatically be included in the
-`TOR_MODULES_ALL_ENABLED` variable which is used to build the unit tests. They
-always build everything in order to tests everything.
+`TOR_MODULES_ALL_ENABLED` variable which is used to build the unit tests.
+They always build everything in order to test everything.
 
 ## Coding ##
 
-As mentioned above, a module must be isolated in its own directory (name of
-the module) in `src/feature/`.
+As mentioned above, a module should be isolated in its own directories,
+suffixed with the name of the module, in `src/*/`.
 
 There are couples of "rules" you want to follow:
 
diff --git a/doc/HACKING/design/this-not-that.md b/doc/HACKING/design/this-not-that.md
new file mode 100644
index 0000000000..815c7b2fbc
--- /dev/null
+++ b/doc/HACKING/design/this-not-that.md
@@ -0,0 +1,51 @@
+
+Don't use memcmp.  Use {tor,fast}_{memeq,memneq,memcmp}.
+
+Don't use assert.  Use tor_assert or tor_assert_nonfatal or BUG.  Prefer
+nonfatal assertions or BUG()s.
+
+Don't use sprintf or snprintf.  Use tor_asprintf or tor_snprintf.
+
+Don't write hand-written binary parsers.  Use trunnel.
+
+Don't use malloc, realloc, calloc, free, strdup, etc. Use tor_malloc,
+tor_realloc, tor_calloc, tor_free, tor_strdup, etc.
+
+Don't use tor_realloc(x, y\*z). Use tor_reallocarray(x, y, z);
+
+Don't say "if (x) foo_free(x)".  Just foo_free(x) and make sure that
+foo_free(NULL) is a no-op.
+
+Don't use toupper or tolower; use TOR_TOUPPER and TOR_TOLOWER.
+
+Don't use isalpha, isalnum, etc.  Instead use TOR_ISALPHA, TOR_ISALNUM, etc.
+
+Don't use strcat, strcpy, strncat, or strncpy. Use strlcat and strlcpy
+instead.
+
+Don't use tor_asprintf then smartlist_add; use smartlist_add_asprintf.
+
+Don't use any of these functions: they aren't portable. Use the
+version prefixed with `tor_` instead: strtok_r, memmem, memstr,
+asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton,
+getpass, ntohll, htonll, strdup,   (This list is incomplete.)
+
+Don't create or close sockets directly. Instead use the wrappers in
+compat.h.
+
+When creating new APIs, only use 'char \*' to represent 'pointer to a
+nul-terminated string'.  Represent 'pointer to a chunk of memory' as
+'uint8_t \*'.  (Many older Tor APIs ignore this rule.)
+
+Don't encode/decode u32, u64, or u16 to byte arrays by casting
+pointers. That can crash if the pointers aren't aligned, and can cause
+endianness problems.  Instead say something more like set_uint32(ptr,
+htonl(foo)) to encode, and ntohl(get_uint32(ptr)) to decode.
+
+Don't declare a 0-argument function with "void foo()".  That's C++
+syntax. In C you say "void foo(void)".
+
+When creating new APIs, use const everywhere you reasonably can.
+
+Sockets should have type tor_socket_t, not int.
+