[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [ooni-probe/master] Port MK's CONTRIBUTING.md to ooni-probe (#607)



commit a34e9525766f8715f09f1e1fe866cb58f506c017
Author: Simone Basso <bassosimone@xxxxxxxxx>
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@xxxxxxxxxx: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@xxxxxxxxxxx"
+```
+
+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
+



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits