[tor-commits] [ooni-probe/master] Port MK's CONTRIBUTING.md to ooni-probe (#607)
art at torproject.org
art at torproject.org
Fri Oct 14 19:00:56 UTC 2016
commit a34e9525766f8715f09f1e1fe866cb58f506c017
Author: Simone Basso <bassosimone at gmail.com>
Date: Fri Oct 7 16:10:11 2016 +0200
Port MK's CONTRIBUTING.md to ooni-probe (#607)
* Port MK's CONTRIBUTING.md to ooni-probe
* fix indentation
* grammar
* more grammar
* Fix command to run ooni tests
---
CONTRIBUTING.md | 87 ++++++++++++++++
HACKING | 286 ---------------------------------------------------
docs/coding-style.md | 193 ++++++++++++++++++++++++++++++++++
3 files changed, 280 insertions(+), 286 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a671ac3
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,87 @@
+# Contributing to ooni-probe
+
+ooni-probe is a Free and Open Source software project that welcomes
+new contributions.
+
+## How to contribute code
+
+For guidelines on what coding style we follow refer to
+the [coding style document](/doc/coding-style.md).
+
+### 1. Fork
+
+You should first create a fork of ooni-probe by clicking on the fork button
+and cloning your fork with:
+
+```
+git clone git at github.com:username/ooni-probe.git
+cd ooni-probe
+git remote add upstream https://github.com/TheTorProject/ooni-probe.git
+```
+
+### 2. Branch
+
+Branches should be created from the `master` branch with an accurately
+labelled name.
+
+If you want to work on a new feature you could name your branch
+`feature/myfeature`, if you are fixing a bug you could name it `bug/1234`.
+
+Create your branch from `master` like so:
+
+```
+git checkout -b mybranch
+```
+
+Then you can start hacking
+
+### 3. Commit
+
+Make sure git knows your username and email address with the following:
+
+```
+git config --global user.name "Jane Doe"
+git config --global user.email "jane at example.com"
+```
+
+Try to keep the commits made on the branch small (a good branch should only
+address one specific issue).
+
+### 4. Test
+
+Make sure all the existing unittests for ooni-probe are passing.
+
+```
+trial ooni
+```
+
+If you add extra code or modify existing code, be sure that it is covered
+by the existing unittests and if not write them. In general, it would be good
+for pull requests not to reduce the current code coverage of the project.
+
+If you are submitting a branch fixing a bug, you should also be submitting
+a unittest that is capable of reproducing the bug you are attempting to fix.
+
+### 5. Open a Pull Request
+
+You can then push your feature branch to your remote and open a pull request.
+
+## Code Review process
+
+Small pull requests should be tagged as `hotfix` and can be self
+merged. All other pull request should be reviewed by another core
+developer who will take responsibility of the merge. The repository
+should be configured such that it is not possible to merge into
+`master` (or `stable`) if unit tests are not passing.
+
+If the diff is small, squash merge is preferred, otherwise preserve
+the history. In general it is a good idea to keep your branches
+in sync with master and rebase them from time to time before the
+review has happenned. However if the review has already begun it's
+better to merge and resolve the conflicts locally and push the merge
+commit, to allow the reviewer to see how the conflicts were resolved.
+
+Before a release, review the code base, fixing simple bugs directly
+and opening issues to describe more complex required fixes and
+refactoring opportunities. Also during such review make sure that
+the documentation is up to date with the code.
diff --git a/HACKING b/HACKING
deleted file mode 100644
index baa5bb0..0000000
--- a/HACKING
+++ /dev/null
@@ -1,286 +0,0 @@
-Hacking on OONI
-***************
-
-This documents gives guidelines on where to start looking
-for helping out in developing OONI and what guidelines you
-should follow when writing code.
-
-We try to follow the general python best practices and styling
-guides as specified in PEP.
-
- Beautiful is better than ugly.
- Explicit is better than implicit.
- Simple is better than complex.
- Complex is better than complicated.
- Flat is better than nested.
- Sparse is better than dense.
- Readability counts.
- Special cases aren't special enough to break the rules.
- Although practicality beats purity.
- Errors should never pass silently.
- Unless explicitly silenced.
- In the face of ambiguity, refuse the temptation to guess.
- There should be one-- and preferably only one --obvious way to do it.
- Although that way may not be obvious at first unless you're Dutch.
- Now is better than never.
- Although never is often better than *right* now.
- If the implementation is hard to explain, it's a bad idea.
- If the implementation is easy to explain, it may be a good idea.
- Namespaces are one honking great idea -- let's do more of those!
-
- - Tim Peters, The Zen of Python
-
-Code Structure
----------
-
-- HACKING
- The document you are currently reading.
-
-- inputs/
- Contains input files for tests.
-
-- ooni/
- Contains the main ooni probe comand line client
-
-- ooni/inputunit.py
- In here we have functions related to the creation of input
- units. Input units are how the inputs to be fed to tests are
- split up into.
-
-- ooni/nettest.py
- In here is the NetTest API definition. This is how people
- interested in writing ooniprobe tests will be specifying
- them.
-
-- ooni/nodes.py
- Mostly broken code for the remote dispatching of tests.
-
-- ooni/oonicli.py
- In here we take care of running ooniprobe from the command
- line interface
-
-- ooni/reporter.py
- In here goes the logic for the creation of ooniprobe
- reports.
-
-- ooni/runner.py
- Handles running ooni.nettests as well as
- ooni.plugoo.tests.OONITests.
-
-- ooni/settings.py
- Parts of the code related to parsing OONI
- configuration files and making them accessible
- to other components of the software.
-
-- ooni/otime.py
- Generation of timestamps, time conversions and all the rest
-
-- ooni/kit/
- In here go utilities that can be used by tests.
-
-- ooni/utils/
- In here go internal utilities that are useful to ooniprobe
-
-- ooni/geoip.py
- In here go functions related to the understanding of
- geographical information of the probe
-
-- ooni/utils/hacks.py
- When some software has issues and we need to fix it in a
- hackish way, we put it in here. This one day will be empty.
-
-- ooni/utils/log.py
- log realted functions.
-
-- ooni/utils/net.py
- utilities for networking related operations
-
-- ooni/utils/onion.py
- Utilities for working with Tor.
- XXX this code should be removed and merged into txtorcon.
-
-- ooni/utils/txscapy.py
- Tools for making scapy work well with twisted.
-
-- ooniprobe.conf
- The main OONI-probe configuration file. This can be used
- to configure your OONI CLI, tell it where it should report
- to, where the asset files are located, what should be used
- for control, etc.
-
-Test related conventions
-------------------------
-
-These are the conventions for tests that are written in ooniprobe. That is what
-goes inside of nettests/.
-
-Naming
-......
-
-All methods that are relevant to the test should be all lower case separated by
-underscore.
-
-All variables that are specific to your test should be all lower case separated
-by underscore.
-
-Simplicity
-..........
-
-Tests written in ooniprobe should be as short as possible and should contain as
-little code not related to the measurement as possible. It should be possible
-from reading the test to understand what it does without clutter.
-
-Everything that is not related directly to the test should go inside of the
-test template of which the test you are writing is a subclass of.
-
-
-Style guide
------------
-
-This is an extract of the most important parts of PEP-8. When in doubt on
-what code style should be followed first consult this doc, then PEP-8 and
-if all fails use your best judgement or ask for help.
-
-The most important part to read is the following as it contains the guidelines
-of naming of variables, functions and classes, as it does not follow pure
-PEP-8.
-
-Naming convention
-.................
-
-Class names should follow the CapWords convention.
-Note: When using abbreviations in CapWords, capitalize all the letters
- of the abbreviation. Thus HTTPServerError is better than
- HttpServerError.
-
-Exception names should follow the class names convention as exceptions
-should be classes.
-
-Method names should follow camelCase with the first letter non-capital.
-
-Class attributes should also follow camelCase with the first letter non-capital.
-
-Functions should follow camelCase with the first letter non-capital.
-
-Functions and variables that are inside the local scope of a class or method
-should be all lowercase separated by an underscore.
-
-Indentation
-...........
-
- Use 4 spaces per indentation level.
-
- This can be setup in vi with:
- set tabstop=4
- set shiftwidth=4
- set expandtab
-
-
- Continuation lines should be wrapper like this:
-
- foo = long_function_name(var_one, var_two,
- var_three, var_four)
-
- or this:
-
- def long_function_name(var_one,
- var_two, var_three,
- var_four):
- print(var_one)
-
-
- They should NOT be wrapper like this:
-
- foo = long_function_name(var_one, var_two,
- var_three, var_four)
-
- and NOT like this:
-
- # See how it creates confusion with what is inside the function?
- def long_function_name(var_one,
- var_two, var_three,
- var_four):
- print(var_one)
-
-
-Tabs or Spaces?
-...............
-
-Every time you insert a \t into any piece of code a kitten dies.
-
-Only spaces. Please.
-
-(code should be run with python -tt)
-
-Maximum Line Length
-...................
-
-Maximum of 79 characters. 72 characters for long blocks of text is recommended.
-
-Blank Lines
-...........
-
-Separate top-level function and class definitions with two blank lines.
-
-Method definitions inside of class are separated by a single blank line.
-
-
-Encoding
-........
-
-Always use UTF-8 encoding. This can be specified by adding the encoding cookie
-to the beginning of your python files:
-
- # -*- coding: UTF-8
-
-All identifiers should be ASCII-only. All doc strings and comments should also
-only be in ASCII. Non ASCII characters are allowed when they are related to
-testing non-ASCII features or for the names of authors.
-
-
-Imports
-.......
-
-Import should be one per line as so:
-
- import os
- import sys
- from subprocess import Popen, PIPE
-
-Imports are always at the top of the file just after any module comments
-and docstrings, berfore module globals and constants.
-
-Imports should be grouped in the following order:
-
-1. standard library imports
-2. related third party imports
-3. local application/library specific imports
-
-You should put a blank line between each group of imports.
-
-
-Comments
-........
-
-Comments should always be up to date with the code. Don't have
-comments that contraddict with the code.
-
-Comments should always be written in English.
-
-Blocks comments are indented to the same level of the code that
-they refer to. They start with # and are followed by a single space.
-
-Use inline comments sparingly. # Gotcha?
-
-
-Documentation strings
-.....................
-
-Write docstrings for all public modules, functions, classes and
-methods. Even better if you write them also for non-public methods.
-
-Place docstrings under the def.
-
-For a better overview on how to write docstrings consult: PEP-257
-
-
diff --git a/docs/coding-style.md b/docs/coding-style.md
new file mode 100644
index 0000000..b1af0cf
--- /dev/null
+++ b/docs/coding-style.md
@@ -0,0 +1,193 @@
+# Hacking on OONI
+
+This documents gives guidelines on where to start looking
+for helping out in developing OONI and what guidelines you
+should follow when writing code.
+
+We try to follow the general python best practices and styling
+guides as specified in PEP.
+
+ Beautiful is better than ugly.
+ Explicit is better than implicit.
+ Simple is better than complex.
+ Complex is better than complicated.
+ Flat is better than nested.
+ Sparse is better than dense.
+ Readability counts.
+ Special cases aren't special enough to break the rules.
+ Although practicality beats purity.
+ Errors should never pass silently.
+ Unless explicitly silenced.
+ In the face of ambiguity, refuse the temptation to guess.
+ There should be one-- and preferably only one --obvious way to do it.
+ Although that way may not be obvious at first unless you're Dutch.
+ Now is better than never.
+ Although never is often better than *right* now.
+ If the implementation is hard to explain, it's a bad idea.
+ If the implementation is easy to explain, it may be a good idea.
+ Namespaces are one honking great idea -- let's do more of those!
+
+ - Tim Peters, The Zen of Python
+
+## Test related conventions
+
+These are the conventions for tests that are written in ooniprobe. That is what
+goes inside of nettests/.
+
+### Naming
+
+All methods that are relevant to the test should be all lower case separated by
+underscore.
+
+All variables that are specific to your test should be all lower case separated
+by underscore.
+
+### Simplicity
+
+Tests written in ooniprobe should be as short as possible and should contain as
+little code not related to the measurement as possible. It should be possible
+from reading the test to understand what it does without clutter.
+
+Everything that is not related directly to the test should go inside of the
+test template of which the test you are writing is a subclass of.
+
+
+## Style guide
+
+This is an extract of the most important parts of PEP-8. When in doubt on
+what code style should be followed first consult this doc, then PEP-8 and
+if all fails use your best judgement or ask for help.
+
+The most important part to read is the following as it contains the guidelines
+of naming of variables, functions and classes, as it does not follow pure
+PEP-8.
+
+### Naming convention
+
+Class names should follow the CapWords convention.
+Note: When using abbreviations in CapWords, capitalize all the letters
+ of the abbreviation. Thus HTTPServerError is better than
+ HttpServerError.
+
+Exception names should follow the class names convention as exceptions
+should be classes.
+
+Method names should follow camelCase with the first letter non-capital.
+
+Class attributes should also follow camelCase with the first letter non-capital.
+
+Functions should follow camelCase with the first letter non-capital.
+
+Functions and variables that are inside the local scope of a class or method
+should be all lowercase separated by an underscore.
+
+### Indentation
+
+Use 4 spaces per indentation level.
+
+ This can be setup in vi with:
+ set tabstop=4
+ set shiftwidth=4
+ set expandtab
+
+
+Continuation lines should be wrapped like this:
+
+ foo = long_function_name(var_one, var_two,
+ var_three, var_four)
+
+or this:
+
+ def long_function_name(var_one,
+ var_two, var_three,
+ var_four):
+ print(var_one)
+
+
+They should NOT be wrapped like this:
+
+ foo = long_function_name(var_one, var_two,
+ var_three, var_four)
+
+and NOT like this:
+
+ # See how it creates confusion with what is inside the function?
+ def long_function_name(var_one,
+ var_two, var_three,
+ var_four):
+ print(var_one)
+
+
+### Tabs or Spaces?
+
+Every time you insert a \t into any piece of code a kitten dies.
+
+Only spaces. Please.
+
+(code should be run with python -tt)
+
+### Maximum Line Length
+
+Maximum of 79 characters. 72 characters for long blocks of text is recommended.
+
+### Blank Lines
+
+Separate top-level function and class definitions with two blank lines.
+
+Method definitions inside of class are separated by a single blank line.
+
+
+### Encoding
+
+Always use UTF-8 encoding. This can be specified by adding the encoding cookie
+to the beginning of your python files:
+
+ # -*- coding: UTF-8
+
+All identifiers should be ASCII-only. All doc strings and comments should also
+only be in ASCII. Non ASCII characters are allowed when they are related to
+testing non-ASCII features or for the names of authors.
+
+
+### Imports
+
+Import should be one per line as so:
+
+ import os
+ import sys
+ from subprocess import Popen, PIPE
+
+Imports are always at the top of the file just after any module comments
+and docstrings, berfore module globals and constants.
+
+Imports should be grouped in the following order:
+
+1. standard library imports
+2. related third party imports
+3. local application/library specific imports
+
+You should put a blank line between each group of imports.
+
+
+### Comments
+
+Comments should always be up to date with the code. Don't have
+comments that contraddict with the code.
+
+Comments should always be written in English.
+
+Blocks comments are indented to the same level of the code that
+they refer to. They start with # and are followed by a single space.
+
+Use inline comments sparingly. # Gotcha?
+
+
+### Documentation strings
+
+Write docstrings for all public modules, functions, classes and
+methods. Even better if you write them also for non-public methods.
+
+Place docstrings under the def.
+
+For a better overview on how to write docstrings consult: PEP-257
+
More information about the tor-commits
mailing list