[tor-commits] [tor/master] Update README files with common style.
nickm at torproject.org
nickm at torproject.org
Fri Mar 27 13:15:39 UTC 2020
commit fd6a35eb59f1d8bce6afc773d0c44937326e0034
Author: Bartosz Duszel <bartosz.duszel at protonmail.com>
Date: Sun Mar 22 13:50:58 2020 +0100
Update README files with common style.
- external links use markdown's []() format,
- local files are formated with backquotes,
- duplicated new lines were removed,
- unnecesary single spaces were removed,
- broken links and local paths were updated.
---
README | 5 ++-
doc/HACKING/CodingStandards.md | 9 ++----
doc/HACKING/CodingStandardsRust.md | 25 ++++++++-------
doc/HACKING/GettingStarted.md | 62 +++++++++++++++++---------------------
doc/HACKING/GettingStartedRust.md | 29 ++++++++----------
doc/HACKING/README.1st.md | 25 ++++++++-------
doc/HACKING/ReleasingTor.md | 5 ---
doc/HACKING/WritingTests.md | 5 ---
8 files changed, 71 insertions(+), 94 deletions(-)
diff --git a/README b/README
index 9e0f4b824..9bbf027d7 100644
--- a/README
+++ b/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
diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md
index 799972416..bcb945bef 100644
--- a/doc/HACKING/CodingStandards.md
+++ b/doc/HACKING/CodingStandards.md
@@ -34,7 +34,7 @@ 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:
@@ -42,7 +42,6 @@ If you have changed build system components:
- For example, if you have changed Makefiles, autoconf files, or anything
else that affects the build system.
-
License issues
==============
@@ -58,7 +57,6 @@ Some compatible licenses include:
- 2-clause BSD
- CC0 Public Domain Dedication
-
How we use Git branches
=======================
@@ -91,7 +89,6 @@ 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
==================
@@ -250,7 +247,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,7 +277,6 @@ 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?
----------------------------------
@@ -424,7 +419,7 @@ do your own profiling to determine otherwise.
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.
diff --git a/doc/HACKING/CodingStandardsRust.md b/doc/HACKING/CodingStandardsRust.md
index b570e10dc..f3b6485e9 100644
--- a/doc/HACKING/CodingStandardsRust.md
+++ b/doc/HACKING/CodingStandardsRust.md
@@ -1,11 +1,10 @@
-
- Rust Coding Standards
+Rust Coding Standards
=======================
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.
@@ -54,7 +53,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
@@ -81,7 +80,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,
@@ -101,7 +100,7 @@ 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.
@@ -118,13 +117,13 @@ 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.
@@ -148,7 +147,7 @@ should put:
}
}
- Benchmarking
+Benchmarking
--------------
The external `test` crate can be used for most benchmarking. However, using
@@ -186,14 +185,14 @@ 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)
@@ -201,7 +200,7 @@ 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
diff --git a/doc/HACKING/GettingStarted.md b/doc/HACKING/GettingStarted.md
index 7d5397d70..cb116cb57 100644
--- a/doc/HACKING/GettingStarted.md
+++ b/doc/HACKING/GettingStarted.md
@@ -1,22 +1,19 @@
-
Getting started in Tor development
==================================
Congratulations! You've found this file, and you're reading it! This
means that you might be interested in getting started in developing Tor.
-(This guide is just about Tor itself--the small network program at the
+(_This guide is just about Tor itself--the small network program at the
heart of the Tor network--and not about all the other programs in the
-whole Tor ecosystem.)
-
+whole Tor ecosystem._)
If you are looking for a more bare-bones, less user-friendly information
dump of important information, you might like reading the
-doxygen output at https://src-ref.docs.torproject.org/tor/index.html .
-You should probably skim some of the topic headings there before you write
+[doxygen output](https://src-ref.docs.torproject.org/tor/index.html).
+You probably should skim some of the topic headings there before you write
your first patch.
-
Required background
-------------------
@@ -27,13 +24,12 @@ and any high-quality guide to C for information on programming.)
I'm also going to assume that you know a little bit about how to use
Git, or that you're able to follow one of the several excellent guides
-at http://git-scm.org to learn.
+at [git-scm](http://git-scm.org) to learn.
-Most Tor developers develop using some Unix-based system, such as Linux,
-BSD, or OSX. It's okay to develop on Windows if you want, but you're
+Most Tor developers develop using some Unix-based system, such as GNU/Linux,
+BSD, or macOS. It's okay to develop on Windows if you want, but you're
going to have a more difficult time.
-
Getting your first patch into Tor
---------------------------------
@@ -42,7 +38,7 @@ Once you've reached this point, here's what you need to know.
1. Get the source.
We keep our source under version control in Git. To get the latest
- version, run
+ version, run:
git clone https://git.torproject.org/git/tor
@@ -52,18 +48,16 @@ Once you've reached this point, here's what you need to know.
git checkout maint-0.4.3
- 2. Find your way around the source
-
- Our overall code structure is explained in our source documentation,
- currently at
+ 2. Find your way around the source.
- https://src-ref.docs.torproject.org/tor/index.html
+ Our overall code structure is explained in our
+ [source documentation](https://src-ref.docs.torproject.org/tor/index.html).
Find a part of the code that looks interesting to you, and start
looking around it to see how it fits together!
We do some unusual things in our codebase. Our testing-related
- practices and kludges are explained in doc/WritingTests.txt.
+ practices and kludges are explained in `.../doc/HACKING/WritingTests.md`.
If you see something that doesn't make sense, we love to get
questions!
@@ -75,10 +69,10 @@ Once you've reached this point, here's what you need to know.
Many people have gotten started by looking for an area where they
personally felt Tor was underperforming, and investigating ways to
- fix it. If you're looking for ideas, you can head to our bug
- tracker at trac.torproject.org and look for tickets that have
- received the "easy" tag: these are ones that developers think would
- be pretty simple for a new person to work on. For a bigger
+ fix it. If you're looking for ideas, you can head to
+ [trac](https://trac.torproject.org) our bug tracking tool and look for
+ tickets that have received the "easy" tag: these are ones that developers
+ think would be pretty simple for a new person to work on. For a bigger
challenge, you might want to look for tickets with the "lorax"
keyword: these are tickets that the developers think might be a
good idea to build, but which we have no time to work on any time
@@ -97,7 +91,7 @@ Once you've reached this point, here's what you need to know.
4. Meet the developers!
- We discuss stuff on the tor-dev mailing list and on the #tor-dev
+ We discuss stuff on the tor-dev mailing list and on the `#tor-dev`
IRC channel on OFTC. We're generally friendly and approachable,
and we like to talk about how Tor fits together. If we have ideas
about how something should be implemented, we'll be happy to share
@@ -114,8 +108,8 @@ Once you've reached this point, here's what you need to know.
protocols, there needs to be a written design proposal before it
can be merged. (We use this process to manage changes in the
protocols.) To write one, see the instructions at
- https://gitweb.torproject.org/torspec.git/tree/proposals/001-process.txt
- . If you'd like help writing a proposal, just ask! We're happy to
+ [the Tor proposal process](https://gitweb.torproject.org/torspec.git/plain/proposals/001-process.txt).
+ If you'd like help writing a proposal, just ask! We're happy to
help out with good ideas.
You might also like to look around the rest of that directory, to
@@ -126,7 +120,7 @@ Once you've reached this point, here's what you need to know.
As you write your code, you'll probably want it to fit in with the
standards of the rest of the Tor codebase so it will be easy for us
to review and merge. You can learn our coding standards in
- doc/HACKING.
+ `.../doc/HACKING` directory.
If your patch is large and/or is divided into multiple logical
components, remember to divide it into a series of Git commits. A
@@ -138,16 +132,16 @@ Once you've reached this point, here's what you need to know.
ensure that it runs correctly. Also, all code should actually be
_run_ by somebody, to make sure it works.
- See doc/WritingTests.txt for more information on how we test things
+ See `.../doc/HACKING/WritingTests.md` for more information on how we test things
in Tor. If you'd like any help writing tests, just ask! We're
glad to help out.
8. Submitting your patch
We review patches through tickets on our bugtracker at
- trac.torproject.org. You can either upload your patches there, or
+ [trac](https://trac.torproject.org). You can either upload your patches there, or
put them at a public git repository somewhere we can fetch them
- (like github or bitbucket) and then paste a link on the appropriate
+ (like gitlab, github or bitbucket) and then paste a link on the appropriate
trac ticket.
Once your patches are available, write a short explanation of what
@@ -164,17 +158,17 @@ Once you've reached this point, here's what you need to know.
When your patch is reviewed, one of these things will happen:
- * The reviewer will say "looks good to me" and your
+ * The reviewer will say "_looks good to me_" and your
patch will get merged right into Tor. [Assuming we're not
in the middle of a code-freeze window. If the codebase is
frozen, your patch will go into the next release series.]
- * OR the reviewer will say "looks good, just needs some small
- changes!" And then the reviewer will make those changes,
+ * OR the reviewer will say "_looks good, just needs some small
+ changes!_" And then the reviewer will make those changes,
and merge the modified patch into Tor.
- * OR the reviewer will say "Here are some questions and
- comments," followed by a bunch of stuff that the reviewer
+ * OR the reviewer will say "_Here are some questions and
+ comments,_" followed by a bunch of stuff that the reviewer
thinks should change in your code, or questions that the
reviewer has.
diff --git a/doc/HACKING/GettingStartedRust.md b/doc/HACKING/GettingStartedRust.md
index aa29c097d..14ab87136 100644
--- a/doc/HACKING/GettingStartedRust.md
+++ b/doc/HACKING/GettingStartedRust.md
@@ -1,8 +1,7 @@
-
- Hacking on Rust in Tor
+Hacking on Rust in Tor
========================
- Getting Started
+Getting Started
-----------------
Please read or review our documentation on Rust coding standards
@@ -23,7 +22,7 @@ Please be patient with the other people who are working on getting more
Rust code into Tor, because they are graciously donating their free time
to contribute to this effort.
- Resources for learning Rust
+Resources for learning Rust
-----------------------------
**Beginning resources**
@@ -49,7 +48,7 @@ is
For learning more about FFI and Rust, see Jake Goulding's
[Rust FFI Omnibus](http://jakegoulding.com/rust-ffi-omnibus/).
- Compiling Tor with Rust enabled
+Compiling Tor with Rust enabled
---------------------------------
You will need to run the `configure` script with the `--enable-rust`
@@ -79,7 +78,7 @@ you are in the top level of the repository) configure tor with:
TOR_RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust
-(Note that TOR_RUST_DEPENDENCIES must be the full path to the directory; it
+(Note that `TOR_RUST_DEPENDENCIES` must be the full path to the directory; it
cannot be relative.)
Assuming you used the above `git submodule` commands and you're in the
@@ -87,8 +86,7 @@ topmost directory of the repository, this would be:
TOR_RUST_DEPENDENCIES=`pwd`/src/ext/rust/crates ./configure --enable-rust
-
- Identifying which modules to rewrite
+Identifying which modules to rewrite
======================================
The places in the Tor codebase that are good candidates for porting to
@@ -117,12 +115,12 @@ interconnected your target module is.
The output will tell you each module name, along with a set of every module that
the module calls. Modules which call fewer other modules are better targets.
- Writing your Rust module
+Writing your Rust module
==========================
Strive to change the C API as little as possible.
-We are currently targetting Rust stable. (See CodingStandardsRust.md for more
+We are currently targetting Rust stable. (See `CodingStandardsRust.md` for more
details.)
It is on our TODO list to try to cultivate good
@@ -134,14 +132,13 @@ If parts of your Rust code needs to stay in sync with C code (such as
handling enums across the FFI boundary), annonotate these places in a
comment structured as follows:
- /// C_RUST_COUPLED: <path_to_file> `<name_of_c_object>`
+ `/// C_RUST_COUPLED: <path_to_file> <name_of_c_object>`
-Where <name_of_c_object> can be an enum, struct, constant, etc. Then,
+Where `<name_of_c_object>` can be an enum, struct, constant, etc. Then,
do the same in the C code, to note that rust will need to be changed
when the C does.
-
- Adding your Rust module to Tor's build system
+Adding your Rust module to Tor's build system
-----------------------------------------------
0. Your translation of the C module should live in its own crate(s)
@@ -156,7 +153,7 @@ dependency of other Rust modules):
`src/rust/tor_util/Cargo.toml` and include it in
`src/rust/tor_rust/lib.rs`
- How to test your Rust code
+How to test your Rust code
----------------------------
Everything should be tested full stop. Even non-public functionality.
@@ -177,7 +174,7 @@ Tor's integration tests should also pass:
make test-stem
- Submitting a patch
+Submitting a patch
=====================
Please follow the instructions in `.../doc/HACKING/GettingStarted.md`.
diff --git a/doc/HACKING/README.1st.md b/doc/HACKING/README.1st.md
index 8299fe634..376bbfb6a 100644
--- a/doc/HACKING/README.1st.md
+++ b/doc/HACKING/README.1st.md
@@ -1,17 +1,17 @@
-
In this directory
-----------------
This directory has helpful information about what you need to know to
hack on Tor!
-First, read `GettingStarted.md` to learn how to get a start in Tor
-development.
+First, read `GettingStarted.md` and `GettingStartedRust.md`
+to learn how to get a start in Tor development.
-If you've decided to write a patch, `CodingStandards.txt` will give
-you a bunch of information about how we structure our code.
+If you've decided to write a patch, `CodingStandards.md` and
+`CodingStandardsRust.md` will give you a bunch of information
+about how we structure our code.
-It's important to get code right! Reading `WritingTests.md` will
+It's important to get the code right! Reading `WritingTests.md` will
tell you how to write and run tests in the Tor codebase.
There are a bunch of other programs we use to help maintain and
@@ -21,22 +21,25 @@ with Tor.
If it's your job to put out Tor releases, see `ReleasingTor.md` so
that you don't miss any steps!
-
+Additional Information
-----------------------
For full information on how Tor is supposed to work, look at the files in
-`https://gitweb.torproject.org/torspec.git/tree`.
+[Tor specification](https://gitweb.torproject.org/torspec.git/tree).
For an explanation of how to change Tor's design to work differently, look at
-`https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/001-process.txt`.
+[the Tor proposal process](https://gitweb.torproject.org/torspec.git/plain/proposals/001-process.txt).
For the latest version of the code, get a copy of git, and
git clone https://git.torproject.org/git/tor
+Stay in touch
+-----------------------
+
We talk about Tor on the `tor-talk` mailing list. Design proposals and
discussion belong on the `tor-dev` mailing list. We hang around on
-irc.oftc.net, with general discussion happening on #tor and development
+irc.oftc.net, with general discussion happening on `#tor` and development
happening on `#tor-dev`.
The other files in this `HACKING` directory may also be useful as you
@@ -44,7 +47,7 @@ get started working with Tor.
Happy hacking!
-
+TODO
-----------------------
XXXXX also describe
diff --git a/doc/HACKING/ReleasingTor.md b/doc/HACKING/ReleasingTor.md
index 0f453ca2a..fbc5de54e 100644
--- a/doc/HACKING/ReleasingTor.md
+++ b/doc/HACKING/ReleasingTor.md
@@ -1,4 +1,3 @@
-
Putting out a new release
-------------------------
@@ -51,10 +50,8 @@ new Tor release:
libevent and openssl, so using valgrind will sometimes find extra
memory leaks.)
-
### II. Write a changelog
-
1a. (Alpha release variant)
Gather the `changes/*` files into a changelog entry, rewriting many
@@ -138,7 +135,6 @@ new Tor release:
to start sorting and condensing entries. (Generally, we don't edit the
text of existing entries, though.)
-
### III. Making the source release.
1. In `maint-0.?.x`, bump the version number in `configure.ac` and run
@@ -215,7 +211,6 @@ new Tor release:
Include a link to the changelog.
-
4. Add the version number to Trac. To do this, go to Trac, log in,
select "Admin" near the top of the screen, then select "Versions" from
the menu on the left. At the right, there will be an "Add version"
diff --git a/doc/HACKING/WritingTests.md b/doc/HACKING/WritingTests.md
index 05de8e0be..c619ef386 100644
--- a/doc/HACKING/WritingTests.md
+++ b/doc/HACKING/WritingTests.md
@@ -126,7 +126,6 @@ unreached lines with 'x', and excluded reached lines with '!!!'.
Note: you should never do this unless the line is meant to 100%
unreachable by actual code.
-
What kinds of test should I write?
----------------------------------
@@ -269,7 +268,6 @@ it's supposed to do, and fail otherwise. Try to design your tests so
that they check for the code's intended and documented functionality
as much as possible.
-
### Mock functions for testing in isolation
Often we want to test that a function works right, but the function to
@@ -382,7 +380,6 @@ Based on the implementation, we now see three more edge cases to test:
* Removing an element from the end of the list
* Removing an element from a position other than the end of the list.
-
### What should my tests NOT do?
Tests shouldn't require a network connection.
@@ -401,7 +398,6 @@ When possible, tests should not be over-fit to the implementation. That is,
the test should verify that the documented behavior is implemented, but
should not break if other permissible behavior is later implemented.
-
### Advanced techniques: Namespaces
Sometimes, when you're doing a lot of mocking at once, it's convenient to
@@ -414,7 +410,6 @@ them, you define `NS_MODULE` to a prefix to be used for your identifiers, and
then use other macros in place of identifier names. See `src/test/test.h` for
more documentation.
-
Integration tests: Calling Tor from the outside
-----------------------------------------------
More information about the tor-commits
mailing list