ryu/CONTRIBUTING.rst

   1 *******************************
   2 How to Get Your Change Into Ryu
   3 *******************************
   4
   5 Submitting a change
   6 ===================
   7
   8 Send patches to ryu-devel@lists.sourceforge.net. Please don't use "Pull
   9 Request" on GitHub. We expect you to send patches in "git-format-patch"
  10 style.
  11
  12 .. code-block:: bash
  13
  14   # "N" means the number of commits to be included
  15   $ git format-patch -s HEAD~N
  16
  17   # To add cover (e.g., [PATCH 0/X]), specify "--cover-letter" option
  18   $ git format-patch -s --cover-letter HEAD~N
  19
  20   # You can send patches by "git send-email" command
  21   $ git send-email --to="ryu-devel@lists.sourceforge.net" *.patch
  22
  23 Please check your changes with autopep8, pycodestyle(pep8) and running
  24 unit tests to make sure that they don't break the existing features.
  25 The following command does all for you.
  26
  27 .. code-block:: bash
  28
  29   # Install dependencies of tests
  30   $ pip install -r tools/test-requires
  31
  32   # Execute autopep8
  33   # Also, it is convenient to add settings of your editor or IDE for
  34   # applying autopep8 automatically.
  35   $ autopep8 --recursive --in-place ryu/
  36
  37   # Execute unit tests and pycodestyle(pep8)
  38   $ ./run_tests.sh
  39
  40 Of course, you are encouraged to add unit tests when you add new
  41 features (it's not a must though).
  42
  43 Python version and libraries
  44 ============================
  45 * Python 2.7, 3.4, 3.5:
  46
  47   Ryu supports multiple Python version.  CI tests on Travis-CI is running
  48   on these versions.
  49
  50 * standard library + widely used library:
  51
  52   Basically widely used == OpenStack adopted.
  53   As usual there are exceptions.  Or python binding library for other
  54   component.
  55
  56 Coding style guide
  57 ==================
  58 * pep8:
  59
  60   As python is used, PEP8 is would be hopefully mandatory for
  61   https://www.python.org/dev/peps/pep-0008/
  62
  63 * pylint:
  64
  65   Although pylint is useful for finding bugs, but pylint score not very
  66   important for now because we're still at early development stage.
  67   https://www.pylint.org/
  68
  69 * Google python style guide is very helpful:
  70   http://google.github.io/styleguide/pyguide.html
  71
  72 * Guidelines derived from Guido's Recommendations:
  73
  74   =============================   =================   ========
  75   Type                            Public              Internal
  76   =============================   =================   ========
  77   Packages                        lower_with_under
  78   Modules                         lower_with_under    _lower_with_under
  79   Classes                         CapWords            _CapWords
  80   Exceptions                      CapWords
  81   Functions                       lower_with_under()  _lower_with_under()
  82   Global/Class Constants          CAPS_WITH_UNDER     _CAPS_WITH_UNDER
  83   Global/Class Variables          lower_with_under    _lower_with_under
  84   Instance Variables              lower_with_under    _lower_with_under (protected) or __lower_with_under (private)
  85   Method Names                    lower_with_under()  _lower_with_under() (protected) or __lower_with_under() (private)
  86   Function/Method Parameters      lower_with_under
  87   Local Variables                 lower_with_under
  88   =============================   =================   ========
  89
  90 * OpenStack Nova style guide:
  91   https://github.com/openstack/nova/blob/master/HACKING.rst
  92
  93 * JSON files:
  94
  95   Ryu source tree has JSON files under ryu/tests/unit/ofproto/json.
  96   They are used by unit tests.  To make patches easier to read,
  97   they are normalized using tools/normalize_json.py.  Please re-run
  98   the script before committing changes to these JSON files.
  99
 100 Reference
 101 =========
 102 * Python Essential Reference, 4th Edition [Amazon]
 103   * Paperback: 717 pages
 104   * Publisher: Addison-Wesley Professional; 4 edition (July 19, 2009)
 105   * Language: English
 106   * ISBN-10: 0672329786
 107   * ISBN-13: 978-0672329784
 108
 109 * The Python Standard Library by Example (Developer's Library)
 110   * Paperback: 1344 pages
 111   * Publisher: Addison-Wesley Professional; 1 edition (June 11, 2011)
 112   * Language: English
 113   * ISBN-10: 0321767349
 114   * ISBN-13: 978-0321767349