[tor-commits] [onionoo/master] Add documentation discussed with iwakeh in #13004.

Fri Sep 12 18:49:47 UTC 2014

commit fce8a56ea1d815f0a66e99148dd5d5b041fc486b
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date:   Fri Sep 12 20:44:19 2014 +0200

    Add documentation discussed with iwakeh in #13004.
---
 CONTRIB.md       |  293 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 HOWTO-VAGRANT.md |   73 --------------
 README.md        |   16 +++
 3 files changed, 309 insertions(+), 73 deletions(-)

diff --git a/CONTRIB.md b/CONTRIB.md
new file mode 100644
index 0000000..244d6a1
--- /dev/null
+++ b/CONTRIB.md
@@ -0,0 +1,293 @@
+# Contributor Guide
+
+This guide is meant for people who want to contribute patches to Onionoo.
+It contains the following sections:
+
+ - Patch format
+ - Whitespace conventions
+ - Vagrant-based development environment
+ - Documentation overview
+
+## Patch format
+
+Format your patches using `git format-patch` if you want to submit just a
+single, small commit.
+If you want to submit more than one commit, push your changes to a public
+Git repository somewhere that can be pulled from.
+
+## Whitespace conventions
+
+Whitespace conventions are important, because whitespace changes bloat
+patches and make them harder to review.
+If we all agree on the same whitespace conventions, the only changes to
+review are actually meaningful changes.
+If you need to make whitespace changes, because files did not conform to
+whitespace conventions before, do these changes in one or more separate
+commits that contain nothing else than whitespace changes.
+
+The following whitespace conventions apply:
+
+ - Maximum line width is 74 characters.  Why 74?  Because it looks pretty
+in vim in a 80-character terminal with line numbers turned on.
+ - Full sentences are followed by a period and two spaces.  An exception
+to this rule are sentences in markup files like Markdown; in this case,
+each sentence should start with a newline, so that a change in one
+sentence doesn't cause changes to all subsequent sentences.  An exception
+to this exception are multiple sentences in a single bullet point.
+ - Indentations use two spaces, no tabs.  Continuations use four spaces.
+ - Attributes and methods are typically separated by two newlines.  An
+exception are attributes with getters and setters which can be written
+without separating newlines.
+ - All source files end with two newlines.
+
+## Vagrant-based development environment
+
+Before using Vagrant, make sure that Onionoo builds correctly on the host
+system.
+This may require running `git submodule init && git submodule update`, as
+well as providing all required libraries.
+
+The given Vagrant file uses Version 2, i.e., a Vagrant installation
+of version 1.1 or above is necessary.
+The following was tested using 1.4.3 and VirtualBox 4.3.14.
+(Wheezy stable only provides 1.0.3, Jessie provides 1.4.3)
+
+Local changes to the Vagrantfile:
+Tell Vagrant how much memory the virtual machine may use, i.e., change
+
+```
+vb.memory = 4096
+```
+
+to some value that makes sense on your machine.
+Rule of thumb: less than half the RAM, but as much as you want to spare.
+
+Create a Debian Wheezy 64 bit instance:
+
+```
+vagrant up
+```
+
+This command downloads the virtual machine imagine, unless it has been
+downloaded before, creates a new virtual machine, and runs the bootstrap
+script in `vagrant/bootstrap.sh`.  This may take a few minutes.
+
+Once this is all done, log into the virtual machine and change to the
+Onionoo working directory:
+
+```
+vagrant ssh
+cd /srv/onionoo.torproject.org/onionoo/
+```
+
+Important: better avoid runninng Ant in the `/vagrant/` directory (which
+is shared with the host), or the guest system will write directly to the
+host system, which performs not really well.
+
+Read the INSTALL file and make the appropriate changes to adapt everything
+to your setup, e.g., memory settings.
+Compile Onionoo, run the unit tests and then the cron part of it:
+
+```
+ant compile
+ant test
+ant run
+```
+
+This step may take an hour or more.  Onionoo downloads the last three days
+of Tor descriptors, which is about 2 GiB, and processes them.
+
+Once these steps are done, deploy the servlet to the local Tomcat server:
+
+```
+ant war
+```
+
+Test the Onionoo service using a browser on the host (port 8080 on the
+guest is forwarded to the host).  Sample URL:
+
+http://localhost:8080/onionoo/summary?limit=2
+
+Note that Tomcat's default server.xml needs no changing for running in the
+development environment.
+See the INSTALL file for necessary changes in the production environment.
+
+## Documentation overview
+
+Onionoo needs documentation for users, service operators, and potential
+contributors.
+
+Users in this case are not so much end users, but developers of Onionoo
+clients;
+end users of Onionoo clients should refer to those clients'
+documentation.
+Service operators are people who run a public Onionoo server.
+Potential contributors are developers who consider writing code for the
+Onionoo server itself.
+
+This document outlines what documentation exists or should exist for
+Onionoo.
+
+### Documentation for users
+
+Most Onionoo users who are interested in reading its documentation are
+developers who write an Onionoo client.
+In addition to that there are a smaller number of people who read user
+documentation to query Onionoo directly rather than using one of the
+available Onionoo clients.
+But for the purpose of this document, most users are interested in reading
+documentation of the RESTful API that Onionoo provides, but they don't
+care much about its Java sources.
+
+#### Overview
+
+The starting point for every user and even every potential contributor is
+the overview page.
+It describes what Onionoo is, lists known Onionoo clients, and points to
+available documentation for users and potential contributors.
+The product overview must be easily accessible, which is why it is
+available via `https://onionoo.torproject.org/`.
+
+The sources of the product overview are available in `web/index.html`.
+
+#### Getting Started guide
+
+New users of the RESTful API may find it overwhelming to read through the
+protocol specification before making their first request.
+A tutorial or Getting Started guide would get these users up to speed
+within 5 or 10 minutes by suggesting some easy requests to make and refine
+towards getting a desired result.
+
+There is a small Getting Started guide available at the bottom of
+`web/protocol.html`.  Maybe it's too well hidden, but it's a start.
+
+#### Protocol specification
+
+Once a user knows what Onionoo provides, they can read up the details in
+its protocol specification.
+This document tells them what requests they can make and how to interpret
+responses.
+Ideally, the protocol specification makes it unnecessary to read up
+further documentation of Tor descriptors.
+A positive side effect of making Onionoo's protocol specification as
+precise as possible is that Onionoo client developers are in a better
+position to make the documentation of Onionoo clients more useful for
+their users.
+
+The sources of the protocol specification can be found in
+`web/protocol.html`.
+
+### Documentation for service operators
+
+A service operator is a person who wants to deploy the Onionoo server.
+That person wouldn't have to understand the inner workings of the Onionoo
+code, but would know enough about it to set it up and handle common
+problems.
+
+#### Deployment Guide
+
+The Deployment Guide explains how to set up a production environment for
+running the Onionoo server and how to deploy Onionoo into it.
+
+There is a somewhat outdated Deployment Guide available in the `INSTALL`
+file.
+It should be updated, moved to a documentation subdirectory, and linked
+from the README file.
+
+### Documentation for potential contributors
+
+A potential contributor is a person who knows what Onionoo provides and
+who wants to help write code (or documentation) for the Onionoo server.
+
+#### README
+
+The README (or README.md) file is the starting point for understanding
+what's in the source tree.
+It should contain a short description of what Onionoo is, in case the
+source tree is the first time the reader gets in touch with Onionoo,
+rather than the overview page.
+The README file should guide the reader by telling them which document to
+read next for what aspect of the Onionoo sources.
+
+#### FAQ
+
+FAQs might be useful for things like:
+
+ - Maven vs. Ant: Maven has its own package manager, Ant lets us use
+Debian packages;
+ - why are certain Java libraries not up-to-date: most recent version
+shipped with Debian stable;
+ - which Java libraries could be used for Onionoo development: whatever is
+in Debian stable, but be sure to ask first;
+
+#### Design document
+
+The design document specifies the operation of the Onionoo server without
+requiring any knowledge of its source code.
+The existing design document in `DESIGN` was written as part of a (failed)
+project to port Onionoo from Java to Python.
+This file is now outdated, and maybe should rather be deleted than
+updated.
+The way how Onionoo operates can also be explained as part of the source
+code documentation.
+
+#### Source code overview
+
+A potential contributor shouldn't be forced to read through source code
+files to understand how these (compiled) files interact with each other.
+There should be an overview of the source code that guides the developer
+where to start reading.
+
+There is currently no such documentation available, but it may be possible
+to write it using JavaDoc's `package-info.java` and have it integrated
+into the generated JavaDoc output (which doesn't exist yet).
+
+#### Source code documentation
+
+Documenting the source code itself makes it easier for a potential
+contributor to understand what it's doing.
+Source code can be documented using JavaDoc comments for inclusion in the
+generated JavaDoc output, or using non-JavaDoc comments to be read
+together with the source code.
+There should be JavaDoc comments for all interfaces and public methods.
+The soon-to-be-available client API could try to provide that from
+scratch.
+
+There is currently little source code documentation in Onionoo, simply
+because the code is self-explanatory!
+More seriously, this needs fixing.
+
+#### Contributor Guide
+
+The Contributor Guide would tell potential contributors how to write,
+test, and submit patches.
+This includes setting up a suitable development environment using Vagrant,
+writing code that conforms to the code style guidelines, up to writing
+useful commit messages and coming up with a good Git history.
+
+There is currently no Contributor Guide for Onionoo, but it would be very
+useful to have one.
+Once it exists it should live in the documentation subdirectory (which
+doesn't exist yet).
+
+#### Coding Rules
+
+A Coding Rules document would contain:
+
+ - naming rules for variables and methods,
+ - JavaDoc conventions,
+ - big _NO_ to uses of `System.out` and `System.err` (as soon as logging
+is in place),
+ - rules about when to use external APIs,
+ - etc.
+
+This document might refer to some standard Java coding guides for
+defaults.
+
+#### Documentation overview
+
+Last but not least, this document should be part of Onionoo's
+documentation.
+The purpose is that contributors know what documentation exists, or should
+not exist, and why.
+
diff --git a/HOWTO-VAGRANT.md b/HOWTO-VAGRANT.md
deleted file mode 100644
index 2cac164..0000000
--- a/HOWTO-VAGRANT.md
+++ /dev/null
@@ -1,73 +0,0 @@
-How to use Vagrant to build and test Onionoo
-============================================
-
-Before using Vagrant, make sure that Onionoo builds correctly on the host
-system.
-This may require running `git submodule init && git submodule update`, as
-well as providing all required libraries.
-
-The given Vagrant file uses Version 2, i.e., a Vagrant installation
-of version 1.1 or above is necessary.
-The following was tested using 1.4.3 and VirtualBox 4.3.14.
-(Wheezy stable only provides 1.0.3, Jessie provides 1.4.3)
-
-Local changes to the Vagrantfile:
-Tell Vagrant how much memory the virtual machine may use, i.e., change
-
-```
-vb.memory = 4096
-```
-
-to some value that makes sense on your machine.
-Rule of thumb: less than half the RAM, but as much as you want to spare.
-
-Create a Debian Wheezy 64 bit instance:
-
-```
-vagrant up
-```
-
-This command downloads the virtual machine imagine, unless it has been
-downloaded before, creates a new virtual machine, and runs the bootstrap
-script in `vagrant/bootstrap.sh`.  This may take a few minutes.
-
-Once this is all done, log into the virtual machine and change to the
-Onionoo working directory:
-
-```
-vagrant ssh
-cd /srv/onionoo.torproject.org/onionoo/
-```
-
-Important: better avoid runninng Ant in the `/vagrant/` directory (which
-is shared with the host), or the guest system will write directly to the
-host system, which performs not really well.
-
-Read the INSTALL file and make the appropriate changes to adapt everything
-to your setup, e.g., memory settings.
-Compile Onionoo, run the unit tests and then the cron part of it:
-
-```
-ant compile
-ant test
-ant run
-```
-
-This step may take an hour or more.  Onionoo downloads the last three days
-of Tor descriptors, which is about 2 GiB, and processes them.
-
-Once these steps are done, deploy the servlet to the local Tomcat server:
-
-```
-ant war
-```
-
-Test the Onionoo service using a browser on the host (port 8080 on the guest
-is forwarded to the host).  Sample URL:
-
-http://localhost:8080/onionoo/summary?limit=2
-
-Note that Tomcat's default server.xml needs no changing for running in the
-development environment.
-See the INSTALL file for necessary changes in the production environment.
-
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..df71660
--- /dev/null
+++ b/README.md
@@ -0,0 +1,16 @@
+# Onionoo
+
+Onionoo is a web-based protocol to learn about currently running Tor
+relays and bridges.  Onionoo itself was not designed as a service for
+human beings---at least not directly.  Onionoo provides the data for other
+applications and websites which in turn present Tor network status
+information to humans.
+
+Onionoo _users_ should head over to `https://onionoo.torproject.org/` to
+learn more about using Onionoo.
+
+Onionoo _service operators_ should read `INSTALL`.
+
+Onionoo _contributors_ should start reading `CONTRIB.md` and, once it's
+available, run `ant doc` and read the generated JavaDocs.
+

