Documentation/faq/contributing.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 ===========
  25 Development
  26 ===========
  27
  28 Q: How do I implement a new OpenFlow message?
  29
  30     A: Add your new message to ``enum ofpraw`` and ``enum ofptype`` in
  31     ``include/openvswitch/ofp-msgs.h``, following the existing pattern.
  32     Then recompile and fix all of the new warnings, implementing new functionality
  33     for the new message as needed.  (If you configure with ``--enable-Werror``, as
  34     described in :doc:`/intro/install/general`, then it is impossible to miss any
  35     warnings.)
  36
  37     To add an OpenFlow vendor extension message (aka experimenter message) for
  38     a vendor that doesn't yet have any extension messages, you will also need
  39     to edit ``build-aux/extract-ofp-msgs`` and at least ``ofphdrs_decode()``
  40     and ``ofpraw_put__()`` in ``lib/ofp-msgs.c``.  OpenFlow doesn't standardize
  41     vendor extensions very well, so it's hard to make the process simpler than
  42     that.  (If you have a choice of how to design your vendor extension
  43     messages, it will be easier if you make them resemble the ONF and OVS
  44     extension messages.)
  45
  46 Q: How do I add support for a new field or header?
  47
  48     A: Add new members for your field to ``struct flow`` in
  49     ``include/openvswitch/flow.h``, and add new enumerations for your new field
  50     to ``enum mf_field_id`` in ``include/openvswitch/meta-flow.h``, following
  51     the existing pattern.  If the field uses a new OXM class, add it to
  52     OXM_CLASSES in ``build-aux/extract-ofp-fields``.  Also, add support to
  53     ``miniflow_extract()`` in ``lib/flow.c`` for extracting your new field from
  54     a packet into struct miniflow, and to ``nx_put_raw()`` in
  55     ``lib/nx-match.c`` to output your new field in OXM matches.  Then recompile
  56     and fix all of the new warnings, implementing new functionality for the new
  57     field or header as needed.  (If you configure with ``--enable-Werror``, as
  58     described in :doc:`/intro/install/general`, then it is impossible to miss
  59     any warnings.)
  60
  61     If you want kernel datapath support for your new field, you also need to
  62     modify the kernel module for the operating systems you are interested in.
  63     This isn't mandatory, since fields understood only by userspace work too
  64     (with a performance penalty), so it's reasonable to start development
  65     without it.  If you implement kernel module support for Linux, then the
  66     Linux kernel "netdev" mailing list is the place to submit that support
  67     first; please read up on the Linux kernel development process separately.
  68     The Windows datapath kernel module support, on the other hand, is
  69     maintained within the OVS tree, so patches for that can go directly to
  70     ovs-dev.
  71
  72 Q: How do I add support for a new OpenFlow action?
  73
  74     A: Add your new action to ``enum ofp_raw_action_type`` in
  75     ``lib/ofp-actions.c``, following the existing pattern.  Then recompile and
  76     fix all of the new warnings, implementing new functionality for the new
  77     action as needed.  (If you configure with ``--enable-Werror``, as described
  78     in the :doc:`/intro/install/general`, then it is impossible to miss any
  79     warnings.)
  80
  81     If you need to add an OpenFlow vendor extension action for a vendor that
  82     doesn't yet have any extension actions, then you will also need to add the
  83     vendor to ``vendor_map`` in ``build-aux/extract-ofp-actions``.  Also, you
  84     will need to add support for the vendor to ``ofpact_decode_raw()`` and
  85     ``ofpact_put_raw()`` in ``lib/ofp-actions.c``.  (If you have a choice of
  86     how to design your vendor extension actions, it will be easier if you make
  87     them resemble the ONF and OVS extension actions.)
  88
  89 Q: How do I add support for a new OpenFlow error message?
  90
  91     A: Add your new error to ``enum ofperr`` in
  92     ``include/openvswitch/ofp-errors.h``.  Read the large comment at the top of
  93     the file for details.  If you need to add an OpenFlow vendor extension
  94     error for a vendor that doesn't yet have any, first add the vendor ID to
  95     the ``<name>_VENDOR_ID`` list in ``include/openflow/openflow-common.h``.
  96
  97 Q: What's a Signed-off-by and how do I provide one?
  98
  99     A: Free and open source software projects usually require a contributor to
 100     provide some assurance that they're entitled to contribute the code that
 101     they provide.  Some projects, for example, do this with a Contributor
 102     License Agreement (CLA) or a copyright assignment that is signed on paper
 103     or electronically.
 104
 105     For this purpose, Open vSwitch has adopted something called the Developer's
 106     Certificate of Origin (DCO), which is also used by the Linux kernel and
 107     originated there.  Informally stated, agreeing to the DCO is the
 108     developer's way of attesting that a particular commit that they are
 109     contributing is one that they are allowed to contribute.  You should visit
 110     https://developercertificate.org/ to read the full statement of the DCO,
 111     which is less than 200 words long.
 112
 113     To certify compliance with the Developer's Certificate of Origin for a
 114     particular commit, just add the following line to the end of your commit
 115     message, properly substituting your name and email address:
 116
 117         Signed-off-by: Firstname Lastname <email@example.org>
 118
 119     Git has special support for adding a Signed-off-by line to a commit
 120     message: when you run "git commit", just add the -s option, as in "git
 121     commit -s".  If you use the "git citool" GUI for commits, you can add a
 122     Signed-off-by line to the commit message by pressing Control+S.  Other Git
 123     user interfaces may provide similar support.
 124
 125 Q: How do I apply patches from email?
 126
 127    A: You can use ``git am`` on raw email contents, either from a file saved by
 128    or piped from an email client.  In ``mutt``, for example, when you are
 129    viewing a patch, you can apply it to the tree in ~/ovs by issuing the
 130    command ``|cd ~/ovs && git am``.  If you are an OVS committer, you might
 131    want to add ``-s`` to sign off on the patch as part of applying it.  If you
 132    do this often, then you can make the keystrokes ``,a`` shorthand for it by
 133    adding the following line to your ``.muttrc``:
 134
 135      macro index,pager ,a "<pipe-message>cd ~/ovs && git am -s" "apply patch"
 136
 137    ``git am`` has a problem with some email messages from the ovs-dev list for
 138    which the mailing list manager edits the From: address, replacing it by the
 139    list's own address.  The mailing list manager must do this for messages
 140    whose sender's email domain has DMARC configured, because receivers will
 141    otherwise discard these messages when they do not come directly from the
 142    sender's email domain.  This editing makes the patches look like they come
 143    from the mailing list instead of the author.  To work around this problem,
 144    one can use the following wrapper script for ``git am``::
 145
 146      #! /bin/sh
 147      tmp=$(mktemp)
 148      cat >$tmp
 149      if grep '^From:.*via dev.*' "$tmp" >/dev/null 2>&1; then
 150         sed '/^From:.*via dev.*/d
 151              s/^[Rr]eply-[tT]o:/From:/' $tmp
 152      else
 153         cat "$tmp"
 154      fi | git am "$@"
 155      rm "$tmp"
 156
 157    Another way to apply emailed patches is to use the ``pwclient`` program,
 158    which can obtain patches from patchwork and apply them directly.  Download
 159    ``pwclient`` at https://patchwork.ozlabs.org/project/openvswitch/.  You
 160    probably want to set up a ``.pwclientrc`` that looks something like this::
 161
 162      [options]
 163      default=openvswitch
 164      signoff=true
 165
 166      [openvswitch]
 167      url=https://patchwork.ozlabs.org/xmlrpc/
 168
 169    After you install ``pwclient``, you can apply a patch from patchwork with
 170    ``pwclient git-am #``, where # is the patch's number.  (This fails with
 171    certain patches that contain form-feeds, due to a limitation of the protocol
 172    underlying ``pwclient``.)
 173
 174    Another way to apply patches directly from patchwork which supports applying
 175    patch series is to use the ``git-pw`` program. It can be obtained with
 176    ``pip install git-pw``. Alternative installation instructions and general
 177    documentation can be found at
 178    https://patchwork.readthedocs.io/projects/git-pw/en/latest/. You need to
 179    use your openvswitch patchwork login or create one at
 180    https://patchwork.ozlabs.org/register/. The following can then be set on
 181    the command line with ``git config`` or through a ``.gitconfig`` like this::
 182
 183      [pw]
 184      server=https://patchwork.ozlabs.org/api/1.0
 185      project=openvswitch
 186      username=<username>
 187      password=<password>
 188
 189    Patch series can be listed with ``git-pw series list`` and applied with
 190    ``git-pw series apply #``, where # is the series number. Individual patches
 191    can be applied with ``git-pw patch apply #``, where # is the patch number.