ticket33688

README

@@ -24,9 +24,8 @@ Making applications work with Tor:
 Frequently Asked Questions:
         https://www.torproject.org/docs/faq.html
 
+Release timeline:
+         https://trac.torproject.org/projects/tor/wiki/org/teams/NetworkTeam/CoreTorReleases
 
 To get started working on Tor development:
         See the doc/HACKING directory.
-
-Release timeline:
-         https://trac.torproject.org/projects/tor/wiki/org/teams/NetworkTeam/CoreTorReleases

doc/HACKING/CircuitPaddingQuickStart.md

@@ -47,6 +47,7 @@ If you want to install on your localsystem, run `make install`. For our case we
 just want the tor binary at `src/app/tor`.
 
 ## Use tor in TB and at a relay
+
 Download and install a fresh Tor Browser (TB) from torproject.org. Make sure it
 works. From the command line, relative to the folder created when you extracted
 TB, run `./Browser/start-tor-browser --verbose` to get some basic log output.
@@ -75,6 +76,7 @@ relay. Start TB, visit a website, and manually confirm that the middle is used
 by looking at the circuit display. 
 
 ## Add a bare-bones APE padding machine
+
 Now the fun part. We have several resources at our disposal (mind that links
 might be broken in the future, just search for the headings):
 - The official [Circuit Padding Developer
@@ -192,6 +194,7 @@ register our machines:
 We run `make` to get a new `tor` binary and copy it to our local TB. 
 
 ## Run the machine
+
 To be able
 to view circuit info events in the console as we launch TB, we add `Log
 [circ]info notice stdout` to `torrc` of TB. 

doc/HACKING/CodeStructure.md

@@ -1,3 +1,4 @@
+# Code Structure
 
 TODO: revise this to talk about how things are, rather than how things
 have changed.

doc/HACKING/CodingStandards.md

@@ -1,5 +1,4 @@
-Coding conventions for Tor
-==========================
+# Coding conventions for Tor
 
 tl;dr:
 
@@ -10,8 +9,7 @@ tl;dr:
    - Run `make distcheck` if you have made changes to build system components
    - Add a file in `changes` for your branch.
 
-Patch checklist
----------------
+## Patch checklist
 
 If possible, send your patch as one of these (in descending order of
 preference)
@@ -34,17 +32,15 @@ Did you remember...
 
 If you are submitting a major patch or new feature, or want to in the future...
 
-   - Set up Chutney and Stem, see HACKING/WritingTests.md
+   - Set up Chutney and Stem, see `doc/HACKING/WritingTests.md`
    - Run `make test-full` to test against all unit and integration tests.
 
 If you have changed build system components:
    - Please run `make distcheck`
    - For example, if you have changed Makefiles, autoconf files, or anything
      else that affects the build system.
 
-
-License issues
-==============
+## License issues
 
 Tor is distributed under the license terms in the LICENSE -- in
 brief, the "3-clause BSD license".  If you send us code to
@@ -58,9 +54,7 @@ Some compatible licenses include:
   - 2-clause BSD
   - CC0 Public Domain Dedication
 
-
-How we use Git branches
-=======================
+## How we use Git branches
 
 Each main development series (like 0.2.1, 0.2.2, etc) has its main work
 applied to a single branch.  At most one series can be the development series
@@ -91,9 +85,7 @@ conflicts in the ChangeLog when it comes time to merge your branch into Tor.
 Best advice: don't try to keep an independent branch forked for more than 6
 months and expect it to merge cleanly. Try to merge pieces early and often.
 
-
-How we log changes
-==================
+## How we log changes
 
 When you do a commit that needs a ChangeLog entry, add a new file to
 the `changes` toplevel subdirectory.  It should have the format of a
@@ -199,8 +191,7 @@ Why use changes files instead of entries in the ChangeLog?
    * Having every single commit touch the ChangeLog file tended to create
    zillions of merge conflicts.
 
-Whitespace and C conformance
-----------------------------
+## Whitespace and C conformance
 
 Invoke `make check-spaces` from time to time, so it can tell you about
 deviations from our C whitespace style.  Generally, we use:
@@ -231,8 +222,7 @@ you're using gcc, you should invoke the configure script with the
 option `--enable-fatal-warnings`.  This will tell the compiler
 to make all warnings into errors.
 
-Functions to use; functions not to use
---------------------------------------
+## Functions to use; functions not to use
 
 We have some wrapper functions like `tor_malloc`, `tor_free`, `tor_strdup`, and
 `tor_gettimeofday;` use them instead of their generic equivalents.  (They
@@ -250,7 +240,6 @@ available containers in `src/lib/containers/*.h`.  You should probably
 familiarize yourself with these modules before you write too much code, or
 else you'll wind up reinventing the wheel.
 
-
 We don't use `strcat` or `strcpy` or `sprintf` of any of those notoriously
 broken old C functions.  We also avoid `strncat` and `strncpy`. Use
 `strlcat`, `strlcpy`, or `tor_snprintf/tor_asprintf` instead.
@@ -281,9 +270,7 @@ version prefixed with `tor_` instead: strtok_r, memmem, memstr,
 asprintf, localtime_r, gmtime_r, inet_aton, inet_ntop, inet_pton,
 getpass, ntohll, htonll.  (This list is incomplete.)
 
-
-What code can use what other code?
-----------------------------------
+## What code can use what other code?
 
 We're trying to simplify Tor's structure over time.  In the long run, we want
 Tor to be structured as a set of modules with *no circular dependencies*.
@@ -300,8 +287,7 @@ included except those specifically permitted by the `.may_include` file.
 When editing one of these files, please make sure that you are not
 introducing any cycles into Tor's dependency graph.
 
-Floating point math is hard
----------------------------
+## Floating point math is hard
 
 Floating point arithmetic as typically implemented by computers is
 very counterintuitive.  Failure to adequately analyze floating point
@@ -360,8 +346,7 @@ For more detailed (and math-intensive) background, see [What Every
 Computer Scientist Should Know About Floating-Point
 Arithmetic](https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html).
 
-Other C conventions
--------------------
+## Other C conventions
 
 The `a ? b : c` trinary operator only goes inside other expressions;
 don't use it as a replacement for if. (You can ignore this inside macro
@@ -370,8 +355,7 @@ definitions when necessary.)
 Assignment operators shouldn't nest inside other expressions.  (You can
 ignore this inside macro definitions when necessary.)
 
-Binary data and wire formats
-----------------------------
+## Binary data and wire formats
 
 Use pointer to `char` when representing NUL-terminated string. To represent
 arbitrary binary data, use pointer to `uint8_t`. (Many older Tor APIs ignore
@@ -390,8 +374,7 @@ for more information about trunnel.
 
 For information on adding new trunnel code to Tor, see src/trunnel/README
 
-Calling and naming conventions
-------------------------------
+## Calling and naming conventions
 
 Whenever possible, functions should return -1 on error and 0 on success.
 
@@ -414,17 +397,15 @@ probably time to create an enum.  If you find that you are passing three or
 more flags to a function, it's probably time to create a flags argument that
 takes a bitfield.
 
-What To Optimize
-----------------
+## What To Optimize
 
 Don't optimize anything if it's not in the critical path.  Right now, the
 critical path seems to be AES, logging, and the network itself.  Feel free to
 do your own profiling to determine otherwise.
 
-Log conventions
----------------
+## Log conventions
 
-`https://www.torproject.org/docs/faq#LogLevel`
+[FAQ - Log Levels](https://www.torproject.org/docs/faq#LogLevel)
 
 No error or warning messages should be expected during normal OR or OP
 operation.
@@ -438,8 +419,7 @@ end-users that they aren't expected to understand the message (perhaps
 with a string like "internal error"). Option (A) is to be preferred to
 option (B).
 
-Assertions In Tor
------------------
+## Assertions In Tor
 
 Assertions should be used for bug-detection only.  Don't use assertions to
 detect bad user inputs, network errors, resource exhaustion, or similar
@@ -458,8 +438,7 @@ macro, as in:
 	if (BUG(ptr == NULL))
 		return -1;
 
-Allocator conventions
----------------------
+## Allocator conventions
 
 By convention, any tor type with a name like `abc_t` should be allocated
 by a function named `abc_new()`.  This function should never return
@@ -500,8 +479,7 @@ to use it as a function callback), define it with a name like
 When deallocating, don't say e.g. `if (x) tor_free(x)`. The convention is to
 have deallocators do nothing when NULL pointer is passed.
 
-Doxygen comment conventions
----------------------------
+## Doxygen comment conventions
 
 Say what functions do as a series of one or more imperative sentences, as
 though you were telling somebody how to be the function.  In other words, DO

doc/HACKING/CodingStandardsRust.md

@@ -1,39 +1,36 @@
+# Rust Coding Standards
 
- Rust Coding Standards
-=======================
-
-You MUST follow the standards laid out in `.../doc/HACKING/CodingStandards.md`,
+You MUST follow the standards laid out in `doc/HACKING/CodingStandards.md`,
 where applicable.
 
- Module/Crate Declarations
----------------------------
+## Module/Crate Declarations
 
 Each Tor C module which is being rewritten MUST be in its own crate.
-See the structure of `.../src/rust` for examples.
+See the structure of `src/rust` for examples.
 
 In your crate, you MUST use `lib.rs` ONLY for pulling in external
 crates (e.g. `extern crate libc;`) and exporting public objects from
 other Rust modules (e.g. `pub use mymodule::foo;`).  For example, if
-you create a crate in `.../src/rust/yourcrate`, your Rust code should
-live in `.../src/rust/yourcrate/yourcode.rs` and the public interface
-to it should be exported in `.../src/rust/yourcrate/lib.rs`.
+you create a crate in `src/rust/yourcrate`, your Rust code should
+live in `src/rust/yourcrate/yourcode.rs` and the public interface
+to it should be exported in `src/rust/yourcrate/lib.rs`.
 
 If your code is to be called from Tor C code, you MUST define a safe
 `ffi.rs`.  See the "Safety" section further down for more details.
 
 For example, in a hypothetical `tor_addition` Rust module:
 
-In `.../src/rust/tor_addition/addition.rs`:
+In `src/rust/tor_addition/addition.rs`:
 
     pub fn get_sum(a: i32, b: i32) -> i32 {
         a + b
     }
 
-In `.../src/rust/tor_addition/lib.rs`:
+In `src/rust/tor_addition/lib.rs`:
 
     pub use addition::*;
 
-In `.../src/rust/tor_addition/ffi.rs`:
+In `src/rust/tor_addition/ffi.rs`:
 
     #[no_mangle]
     pub extern "C" fn tor_get_sum(a: c_int, b: c_int) -> c_int {
@@ -42,7 +39,7 @@ In `.../src/rust/tor_addition/ffi.rs`:
 
 If your Rust code must call out to parts of Tor's C code, you must
 declare the functions you are calling in the `external` crate, located
-at `.../src/rust/external`.
+at `src/rust/external`.
 
 <!-- XXX get better examples of how to declare these externs, when/how they -->
 <!-- XXX are unsafe, what they are expected to do —isis                     -->
@@ -54,8 +51,7 @@ If you have any external modules as dependencies (e.g. `extern crate
 libc;`), you MUST declare them in your crate's `lib.rs` and NOT in any
 other module.
 
- Dependencies and versions
----------------------------
+## Dependencies and versions
 
 In general, we use modules from only the Rust standard library
 whenever possible. We will review including external crates on a
@@ -81,8 +77,7 @@ Currently, Tor requires that you use the latest stable Rust version. At
 some point in the future, we will freeze on a given stable Rust version,
 to ensure backward compatibility with stable distributions that ship it.
 
- Updating/Adding Dependencies
-------------------------------
+## Updating/Adding Dependencies
 
 To add/remove/update dependencies, first add your dependencies,
 exactly specifying their versions, into the appropriate *crate-level*
@@ -101,14 +96,13 @@ Next, run `/scripts/maint/updateRustDependencies.sh`.  Then, go into
 `src/ext/rust` and commit the changes to the `tor-rust-dependencies`
 repo.
 
- Documentation
----------------
+## Documentation
 
 You MUST include `#![deny(missing_docs)]` in your crate.
 
 For function/method comments, you SHOULD include a one-sentence, "first person"
 description of function behaviour (see requirements for documentation as
-described in `.../src/HACKING/CodingStandards.md`), then an `# Inputs` section
+described in `src/HACKING/CodingStandards.md`), then an `# Inputs` section
 for inputs or initialisation values, a `# Returns` section for return
 values/types, a `# Warning` section containing warnings for unsafe behaviours or
 panics that could happen.  For publicly accessible
@@ -118,14 +112,12 @@ types/constants/objects/functions/methods, you SHOULD also include an
 You MUST document your module with _module docstring_ comments,
 i.e. `//!` at the beginning of each line.
 
- Style
--------
+## Style
 
 You SHOULD consider breaking up large literal numbers with `_` when it makes it
 more human readable to do so, e.g. `let x: u64 = 100_000_000_000`.
 
- Testing
----------
+## Testing
 
 All code MUST be unittested and integration tested.
 
@@ -134,7 +126,7 @@ describing how the function/object is expected to be used.
 
 Integration tests SHOULD go into a `tests/` directory inside your
 crate.  Unittests SHOULD go into their own module inside the module
-they are testing, e.g. in `.../src/rust/tor_addition/addition.rs` you
+they are testing, e.g. in `src/rust/tor_addition/addition.rs` you
 should put:
 
     #[cfg(test)]
@@ -148,8 +140,7 @@ should put:
         }
     }
 
- Benchmarking
---------------
+## Benchmarking
 
 The external `test` crate can be used for most benchmarking.  However, using
 this crate requires nightly Rust.  Since we may want to switch to a more
@@ -173,7 +164,7 @@ for basic benchmarks, is only used when running benchmarks via `cargo
 bench --features bench`.
 
 Finally, to write your benchmark code, in
-`.../src/rust/tor_addition/addition.rs` you SHOULD put:
+`src/rust/tor_addition/addition.rs` you SHOULD put:
 
     #[cfg(all(test, features = "bench"))]
     mod bench {
@@ -186,23 +177,20 @@ Finally, to write your benchmark code, in
         }
     }
 
- Fuzzing
----------
+## Fuzzing
 
 If you wish to fuzz parts of your code, please see the
-[`cargo fuzz`](https://github.com/rust-fuzz/cargo-fuzz) crate, which uses
+[cargo fuzz](https://github.com/rust-fuzz/cargo-fuzz) crate, which uses
 [libfuzzer-sys](https://github.com/rust-fuzz/libfuzzer-sys).
 
- Whitespace & Formatting
--------------------------
+## Whitespace & Formatting
 
 You MUST run `rustfmt` (https://github.com/rust-lang-nursery/rustfmt)
 on your code before your code will be merged.  You can install rustfmt
 by doing `cargo install rustfmt-nightly` and then run it with `cargo
 fmt`.
 
- Safety
---------
+## Safety
 
 You SHOULD read [the nomicon](https://doc.rust-lang.org/nomicon/) before writing
 Rust FFI code.  It is *highly advised* that you read and write normal Rust code