commit a34e9525766f8715f09f1e1fe866cb58f506c017 Author: Simone Basso bassosimone@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@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@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 +