Skip to content

Commit b8d5ac2

Browse files
francozappafrancozappa
committed
Draft contributing.rst
1 parent eafda84 commit b8d5ac2

File tree

4 files changed

+211
-69
lines changed

4 files changed

+211
-69
lines changed

‎docs/contributing.rst‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
.. CONTRIBUTING {{{1
2+
.. _contributing:
3+
4+
*************
5+
Contributing
6+
*************
7+
8+
This doc provides information about how to contribute to the MiniCPS
9+
projects.
10+
11+
.. HOW TO START {{{2
12+
13+
=============
14+
How to start
15+
=============
16+
17+
18+
General design principles
19+
-------------------------
20+
21+
MiniCPS follows an object-oriented design pattern. It is using ``python2.x``
22+
for compatibility reasons with ``mininet``. We are trying to lower the number
23+
of external dependencies, and eventually will move to ``python3.x``.
24+
25+
* design drivers:
26+
27+
* separation of concerns (eg: public API vs private APi)
28+
* modularity (eg: different protocols and state backends)
29+
* testability (eg: unit tests and TDD)
30+
* performance (eg: real-time simulation)
31+
32+
* security drivers:
33+
34+
* avoid unsafe programming languages
35+
* user input is untrusted and has to be validated (eg: prepared statements)
36+
* safe vs unsafe code separation
37+
* automated static analysis
38+
39+
* core components:
40+
41+
* ``minicps`` module (should be in the ``PYTHONPATH``)
42+
* ``examples`` use cases (can be anywhere in the filesystem)
43+
44+
45+
Development sytle
46+
-----------------
47+
48+
MiniCPS is hosted on Github and encourages `canonical submission of
49+
contributions
50+
<https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution>`_
51+
it uses
52+
`semantic versioning <http://semver.org/>`_,
53+
``nose`` for `test-driven development
54+
<https://in.pycon.org/2009/smedia/slides/tdd_with_python.pdf>`_ and
55+
``make`` as a launcher for various tasks.
56+
57+
Required code
58+
---------------
59+
60+
Clone the ``minicps`` repository:
61+
62+
.. code-block:: console
63+
64+
git clone https://github.com/scy-phy/minicps
65+
66+
Add ``minicps`` to the python path, for example using a soft link:
67+
68+
.. code-block:: console
69+
70+
ln -s ~/minicps/minicps /usr/lib/python2.7/minicps
71+
72+
73+
Install the requirements using:
74+
75+
.. code-block:: console
76+
77+
pip install -r ~/minicps/requirements.txt
78+
79+
Run the tests with:
80+
81+
.. code-block:: console
82+
83+
cd ~/minicps
84+
make tests
85+
86+
Code conventions
87+
----------------
88+
89+
The project it is based on PEP8 (code) and PEP257 (docstring).
90+
91+
* naming scheme:
92+
93+
* private: prepend ``_`` eg: ``_method_name`` or ``_attribute_name``
94+
* classes: ``ClassName`` or ``CLASSName``, ``method_name`` and ``instance_name``
95+
* others: ``function_name``, ``local_variable_name``, ``GLOBAL_VARIABLE_NAME``
96+
* filenames: ``foldername``, ``module.py``, ``another_module.py``
97+
and ``module_tests.py``
98+
* test: ``test_ClassName`` ``test_function_name``
99+
* make: ``target-name`` ``VARIABLE_NAME``
100+
* makers: ``TODO``, ``FIXME``, ``XXX``, ``NOTE``
101+
* doc: ``doc.rst``, ``another-doc.rst`` \and ``SPHINX_DOC_NAME SOMETHING(`` for
102+
Sphinx's ``literalinclude``
103+
104+
105+
Module docstring:
106+
107+
.. code-block:: python
108+
109+
"""
110+
``modulename`` contains:
111+
112+
- bla
113+
114+
First paragraph.
115+
116+
...
117+
118+
Last paragraph.
119+
"""
120+
121+
Function docstrings:
122+
123+
.. code-block:: python
124+
125+
def my_func():
126+
"""Bla."""
127+
128+
pass
129+
130+
def my_func():
131+
"""Bla.
132+
133+
:returns: wow
134+
"""
135+
136+
pass
137+
138+
Class docstring to document (at least) public methods:
139+
140+
.. code-block:: python
141+
142+
class MyClass(object):
143+
144+
"""Bla."""
145+
146+
def __init__(self):
147+
"""Bla."""
148+
149+
pass
150+
151+
.. }}}
152+
153+
154+
.. PROTOCOLS {{{2
155+
156+
=========
157+
Protocols
158+
=========
159+
160+
Compatibility with new (industrial) protocols depends on the availability of
161+
a good open-source library implementing that protocol (eg: ``pymodbus`` for
162+
Modbus protocols).
163+
164+
If you want to add a new protocol please look at the ``minicps/protocols.py``
165+
module. ``Protocol`` is the base class, and the
166+
``NewProtocolNameProtocol(Protocol)`` should be your new child class containing
167+
the code to manage it. A good point to start it to take a look
168+
at ``minicps/tests/protocols_tests.py`` to see how other protocols classes
169+
are unit-tested.
170+
171+
If you want to improve the compatibility of a supported protocol please take
172+
a look at its implementation and unit-testing classes. For example, look at
173+
``ModbusProtocol(Protocol)`` and ``TestModbusProtocol()`` if you want to improve
174+
the Modbus protocol support.
175+
176+
.. }}}
177+
178+
.. STATES {{{2
179+
180+
======
181+
States
182+
======
183+
184+
The same reasoning presented in the Protocols section applies here.
185+
186+
.. }}}
187+
188+
.. EXAMPLES {{{2
189+
190+
========
191+
Examples
192+
========
193+
194+
Please feel free to send PRs about new use cases that are not already present
195+
in the ``examples`` directory.
196+
197+
.. }}}
198+
199+
.. }}}
200+

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ Contents:
1414
userguide
1515
api
1616
swat-tutorial
17+
contributing
1718
tests
1819
misc
1920

‎docs/swat-tutorial.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@
55
SWaT tutorial
66
*************
77

8-
This tutorial shows how to use MiniCPS to simulate a subprocess of a
8+
This tutorial shows how to use MiniCPS to simulate a subprocess of a
99
Water Treatment testbed. In particular, we demonstrate basic controls through
1010
simulated PLCs, the network traffic, and simple physical layer simulation. We
11-
now provide:
11+
now provide:
1212

1313
* A list of the pre-requisites to run the tutorial
1414
* A brief system overview

‎docs/userguide.rst‎

Lines changed: 8 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -42,55 +42,20 @@ requirements for MiniCPS (e.g., it can be used to display a pop-up window
4242
with sensor data visualization).
4343

4444
The `Install MiniCPS`_ section provides instructions to install ``minicps``
45-
on a machine that is running the **latest official mininet VM (Ubuntu)**. Please
46-
refer to your distribution documentation if you need to install Mininet on
47-
other Linux distributions.
48-
45+
for a user or a developer, and it assumes that you *already* have installed
46+
``mininet``.
4947

5048
.. INSTALL MINICPS {{{3
5149
5250
Install MiniCPS
5351
---------------
5452

55-
Login the OS containing ``mininet`` installation then navigate to your home
56-
directory:
57-
58-
.. code-block:: console
59-
60-
cd
61-
62-
Make sure that the distro is up to date (if necessary, restart the system):
63-
64-
.. code-block:: console
65-
66-
sudo apt-get update
67-
sudo apt-get upgrade
68-
69-
Then clone ``minicps`` repository:
70-
71-
.. code-block:: console
72-
73-
git clone https://github.com/scy-phy/minicps
74-
75-
and add ``minicps`` to the python path, for example using a soft link:
76-
77-
.. code-block:: console
78-
79-
ln -s ~/minicps/minicps /usr/lib/python2.7/minicps
80-
81-
MiniCPS is compatible with *python 2.7.X*. Install dependencies using:
53+
MiniCPS is can be installed using ``pip``:
8254

8355
.. code-block:: console
8456
85-
sudo apt-get install python-matplotlib python-networkx python-pil.imagetk
57+
sudo pip install minicps
8658
87-
For *Ethernet/IP* support install ``cpppo``
88-
89-
.. code-block:: console
90-
91-
sudo pip install cpppo
92-
93-
.. TODO: add modbus maybe reorganize the deps
9459
9560
For *SDN controller development* there are many options,
9661
``pox`` is a good starting point and Mininet's VM already includes it. If you
@@ -109,7 +74,7 @@ execute the following:
10974
11075
~/minicps/bin/pox-init.py [-p POX_PATH -m MINICPS_PATH -vv]
11176
112-
Notice that:
77+
Notice that:
11378

11479
* You can increase the verbosity level using either ``v`` or ``-vv``
11580
* ``POX_PATH`` defaults to ``~/pox`` and ``MINICPS_PATH`` defaults to
@@ -118,41 +83,17 @@ Notice that:
11883
.. INSTALL OPTIONAL {{{3
11984
.. _install-optional:
12085

121-
Install optional dependencies
122-
--------------------------------
123-
124-
For *testing* support install dependencies using:
125-
126-
.. code-block:: console
127-
128-
sudo apt-get install python-pip python-nose python-coverage
129-
sudo pip install nose-cov
130-
131-
To generate the *documentation* from the source we use the ``sphinx`` tool.
132-
Please type:
133-
134-
.. code-block:: console
135-
136-
sudo apt-get install python-sphinx libjs-mathjax
137-
sudo pip install sphinx-rtd-theme
138-
139-
140-
141-
.. TESTING INSTALLATION {{{3
142-
143-
Testing installation
144-
----------------------
14586

146-
Now you should be able to run:
87+
Test the installation with:
14788

14889
.. code-block:: console
14990
15091
cd ~/minicps
15192
make tests
15293
153-
.. Which should start the command line with ``mininet>`` prompt. To directly
154-
.. continue with the tutorial, look at :ref:`swat-tutorial`.
15594
95+
If you want to contribute to the project please take a look at
96+
:ref:`contributing`.
15697

15798
.. CONFIGURE MINICPS {{{2
15899

0 commit comments

Comments
 (0)