From patchwork Fri May 22 15:24:28 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gabriele Cerami X-Patchwork-Id: 1296320 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=openvswitch.org (client-ip=140.211.166.138; helo=whitealder.osuosl.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=iX3axRz6; dkim-atps=neutral Received: from whitealder.osuosl.org (smtp1.osuosl.org [140.211.166.138]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 49T9Jp31BTz9sRW for ; Sat, 23 May 2020 01:24:42 +1000 (AEST) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id AE01888AAC; Fri, 22 May 2020 15:24:40 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id lYNGMpnSQa3t; Fri, 22 May 2020 15:24:39 +0000 (UTC) Received: from lists.linuxfoundation.org (lf-lists.osuosl.org [140.211.9.56]) by whitealder.osuosl.org (Postfix) with ESMTP id 3701288AAF; Fri, 22 May 2020 15:24:39 +0000 (UTC) Received: from lf-lists.osuosl.org (localhost [127.0.0.1]) by lists.linuxfoundation.org (Postfix) with ESMTP id 2A39AC088B; Fri, 22 May 2020 15:24:39 +0000 (UTC) X-Original-To: ovs-dev@openvswitch.org Delivered-To: ovs-dev@lists.linuxfoundation.org Received: from hemlock.osuosl.org (smtp2.osuosl.org [140.211.166.133]) by lists.linuxfoundation.org (Postfix) with ESMTP id 62AFDC0176 for ; Fri, 22 May 2020 15:24:37 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id 5045B88F2E for ; Fri, 22 May 2020 15:24:37 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from hemlock.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 4kmbBBfZ4GrL for ; Fri, 22 May 2020 15:24:36 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by hemlock.osuosl.org (Postfix) with ESMTPS id 5FA7688B52 for ; Fri, 22 May 2020 15:24:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1590161075; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=7XzMY2rJCwUDLNJPia5S7KZgx1nT9zIBmqzgUDQBRb0=; b=iX3axRz6eQ8VeHT7KM1JjpDnBbmX50D7IH1kYpLid0QzXE3OrT/WnEP2ZVR1Gxpo5cjPy1 Xy3AdpBa63UzeFKfm4DYEQYfvZH+YIJHN2B18tnguRX5X787cdw0zw0+0Ra2vs0SScXzFK T/34I3/aDFsWsRCHhXP7gjbSOLVYhec= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-363-zigrTPIQPcGeJ7bmIHbhdw-1; Fri, 22 May 2020 11:24:31 -0400 X-MC-Unique: zigrTPIQPcGeJ7bmIHbhdw-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 7D81E80058A for ; Fri, 22 May 2020 15:24:30 +0000 (UTC) Received: from localhost (unknown [10.36.110.64]) by smtp.corp.redhat.com (Postfix) with ESMTP id CB3215D9CC for ; Fri, 22 May 2020 15:24:29 +0000 (UTC) Date: Fri, 22 May 2020 16:24:28 +0100 From: Gabriele Cerami To: ovs-dev@openvswitch.org Message-ID: <20200522152428.5du7her7v5euqkbs@localhost> MIME-Version: 1.0 User-Agent: NeoMutt/20170113 (1.7.2) X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Disposition: inline Subject: [ovs-dev] [PATCH ovn] Documentation: add a quick start for prospective contributors X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: ovs-dev-bounces@openvswitch.org Sender: "dev" This change adds a small guide that may be useful to prospective contributors that start from scratch. Signed-off-by: Gabriele Cerami --- Documentation/internals/contributing/index.rst | 1 + .../internals/contributing/quickstart.rst | 202 +++++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 Documentation/internals/contributing/quickstart.rst diff --git a/Documentation/internals/contributing/index.rst b/Documentation/internals/contributing/index.rst index 77b52964b..fafc530b6 100644 --- a/Documentation/internals/contributing/index.rst +++ b/Documentation/internals/contributing/index.rst @@ -30,6 +30,7 @@ The below guides provide information on contributing to OVN itself. .. toctree:: :maxdepth: 2 + quickstart submitting-patches backporting-patches coding-style diff --git a/Documentation/internals/contributing/quickstart.rst b/Documentation/internals/contributing/quickstart.rst new file mode 100644 index 000000000..9f6870360 --- /dev/null +++ b/Documentation/internals/contributing/quickstart.rst @@ -0,0 +1,202 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in OVN documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +============================================== +Simple steps if you want to start from scratch +============================================== + +This is a quick reference document on some steps a contributor could make +to ramp up more quickly with knowledge and unstanding of OVN + +Understand the Architecture +--------------------------- + +Take a look at the overall architecture first. + +High level Overview +~~~~~~~~~~~~~~~~~~~ + +This video is from 2016 but content is still relevant and it gives a quick +overview of the various components. + +`OVN introduction `_. + + +In depth architecture +~~~~~~~~~~~~~~~~~~~~~ + +You may want to dive deeper in the architecture after. + +Look at +`OVN architecture `_. + +or from ovn repo root: + +:: + + nroff -man ovn-architecture.7 | less + +Ovsdb +~~~~~ + +The role of ovsdb is central for any activity on ovn. Understand at least the data model, +the schemas, and the monitoring. + +`OVSDB documentation `_. + + +Set a goal for yourself +----------------------- + +Before proceeding further it may be important to set an achievable goal +to give a direction to your study. +Join the weekly meeting, present yourself and ask for things to do + + +Study the code +-------------- + +Knowing the overall architecture it's not difficult to map the components +to the source in the tree, but there may be some abbreviations not immediately familiar. + +Glossary +~~~~~~~~ + +:sbrec/nbrec: + record on southbound/northbound database + +:ic: + interconnection controller + +:idl: + Interface Definition Language. Structures related to the idl help + maintain in-memory replicas of OVSDB instances. + +:hmap/smap: + Hash map implementations that ... ??? + +Data Structures +~~~~~~~~~~~~~~~ + +Keep a tab opened to data structures implementation, and keep in mind that many may +still be imported from ovs repo. + +An example of flow with reference to the code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +How a change in the nb database from the cloud plugin becomes a set of +rules in the ovs switch ? + +1. The northd receives notification of a record from northbound database + + 1.1 northd/ovs_northd.c:??? handles the notification. + +2. ??? +3. ??? + + + +Hands-on +-------- + +Quick Start +~~~~~~~~~~~ + +:: + + git clone https://github.com/openvswitch/ovs + pushd ovs + ./boot.sh ; ./configure ; make + popd + + git clone https://github.com/ovn-org/ovn + ./boot.sh ; ./configure --with-ovs-source=../ovs ; make + popd + + +Playgrounds +~~~~~~~~~~~ + +To do some experiments, there are a few method at disposal: + +A simple non isolated OVS bridge controlled by OVN can be easily created with + +:: + + pushd ovn + make sandbox + + +to create a larger playground wtih multiple bridges in multiple nodes, +look at `OVN fake multinode `_. repo + +Tests +------ + +The test suite is run with the help of autotest. + +Types of tests +~~~~~~~~~~~~~~ + +:component: + WIP + +:end to end: + WIP + +Create a test +~~~~~~~~~~~~~ + +1. ??? +2. Ensure description is present in at_help_all var in tests/testsuite +3. ??? + +Branching Model +--------------- + +WIP + +Your first submission +--------------------- + +Before submitting your patch, review :doc:`internals/contributin/submitting-patches` + +:: + + git checkout -b my-first-patch + + +Modify the code. then. + +:: + + git commit -a --signoff + git format-patch master --prefix "[PATCH ovn - my first patch]" + +edit the .patch file with tags. + +:: + + git send-email --smtp-server=your.smtp.server *.patch + +