docs/add-project-distribution.rst

   1 .. _add-proj-dist:
   2
   3 Add Projects to distribution
   4 ============================
   5
   6 Managed Projects
   7 ----------------
   8
   9 Add features to distribution
  10 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  11
  12 Managed projects must be in the distribution. Follow the steps below
  13 to add your karaf features to distribution:
  14
  15 #. Download int/dist repository:
  16
  17    .. code-block:: bash
  18
  19       git clone ssh://<user>@git.opendaylight.org:29418/integration/distribution
  20
  21 #. Make sure the projects you depend are already in the pom file:
  22
  23    .. code-block:: bash
  24
  25       features/repos/index/pom.xml
  26
  27 #. Check your project version is correct in the file:
  28
  29    .. code-block:: bash
  30
  31       artifacts/upstream/properties/pom.xml
  32
  33 #. Declare your feature repositories and user-facing features dependencies:
  34
  35    If your project artifacts pom.xml contains your karaf feature repos and features,
  36    just add your project artifacts dependency in:
  37
  38    .. code-block:: bash
  39
  40       artifacts/upstream/artifacts/pom.xml
  41
  42    Otherwise add your project feature repositories and your user-facing features to:
  43
  44    .. code-block:: bash
  45
  46       artifacts/upstream/feature-repos/pom.xml
  47       artifacts/upstream/single-features/pom.xml
  48
  49    .. note:: Always add your maven dependencies in alphabethical order.
  50              This also applies to the next steps.
  51
  52 #. Add your feature repositories in:
  53
  54    .. code-block:: bash
  55
  56       features/repos/index/pom.xml
  57
  58 #. Add your user facing features in either:
  59
  60    .. code-block:: bash
  61
  62       features/singles/odl-integration-compatible-with-all/pom.xml
  63
  64    if your feature is compatible.
  65
  66    .. code-block:: bash
  67
  68       features/singles/odl-integration-all/pom.xml
  69
  70    if your feature is not compatible.
  71
  72    .. note:: You do not need to add a feature if it is already contained
  73              in another feature you have already included.
  74
  75    Remember compatible features are those that can co-exist with other features in ODL because:
  76
  77    * They do not interfere with any other feature
  78    * They are not network intrusive (e.g. configure network devices or push flows out-of-the-box)
  79
  80 #. Push changes to int/dist and wait for patch verification and review.
  81
  82    Once the patch is merged your project will be part of the OpenDaylight managed distribution which is
  83    normally available in nexus managed-distribution_ and will join the distribution-check verification.
  84
  85 Trigger distribution build
  86 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  87
  88 Once the project is in the distribution it is recommended to build and publish a new distribution
  89 every time a merge happens in the project. Follow the steps below to add this trigger:
  90
  91 #. Download releng/builder repository:
  92
  93    .. code-block:: bash
  94
  95       git clone ssh://<user>@git.opendaylight.org:29418/releng/builder
  96
  97 #. Add your merge job in following file under distribution-managed section:
  98
  99    .. code-block:: bash
 100
 101       jjb/integration/distribution/distribution-jobs.yaml
 102
 103       - project:
 104           name: distribution-managed
 105           ...
 106           stream:
 107             - fluorine:
 108                 branch: 'master'
 109                 dependencies: >
 110                     aaa-merge-{stream},
 111                     bgpcep-merge-{stream},
 112                     coe-merge-{stream},
 113           ...
 114
 115 #. Push changes to releng/builder and wait for patch verification and review.
 116
 117 Self-Managed Projects
 118 ---------------------
 119
 120 Add features to distribution
 121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 Self-Managed projects must only be in the distribution if they want to be packaged in distribution
 124 and released at the same time as the Managed projects do.
 125
 126 Follow the next steps to add your karaf features to the OpenDaylight distribution:
 127
 128 #. Download int/dist repository:
 129
 130    .. code-block:: bash
 131
 132       git clone ssh://<user>@git.opendaylight.org:29418/integration/distribution
 133
 134 #. Add your feature repository in:
 135
 136    .. code-block:: bash
 137
 138       opendaylight/pom.xml
 139
 140    .. note:: Always add your maven dependencies in alphabethical order.
 141              This also applies to the next steps.
 142
 143 #. Push changes to int/dist and wait for patch verification and review.
 144
 145    Once the patch is merged your project will be part of the new OpenDaylight distribution which is
 146    normally available in nexus full-distribution_.
 147
 148    .. note:: In order to install a Self-Managed feature, you have to first install the feature repository
 149              in karaf, the example below shows how to install a repository from the karaf console.
 150
 151    .. code-block:: bash
 152
 153       opendayligt>feature:repo-add mvn:org.opendaylight.sxp/features-sxp//xml/features
 154
 155    .. note:: If the feature version is not specified in the URL (see example above), Karaf will use
 156              the latest version (normally only one stored) in the the system folder.
 157
 158    .. note:: You can alternatively add the repository in the karaf boot file etc/org.apache.karaf.features.cfg
 159
 160 Add features to sanity test
 161 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 162
 163 Distribution sanity test runs once a day to verify all projects features, managed
 164 and sef-managed, can be installed with no issues. Follow below steps to add your
 165 features to the sanity test.
 166
 167 #. Download releng/builder repository:
 168
 169    .. code-block:: bash
 170
 171       git clone ssh://<user>@git.opendaylight.org:29418/releng/builder
 172
 173 #. Open the distribution-jobs.yaml file:
 174
 175    .. code-block:: bash
 176
 177       jjb/integration/distribution/distribution-jobs.yaml
 178
 179    Add your feature repo and user-facing features in the distribution section:
 180
 181    .. code-block:: bash
 182
 183       stream:
 184         - fluorine:
 185             branch: 'master'
 186             karaf-version: odl
 187             # Self-Managed projects repos and features:
 188             sm-repos: >
 189                 mvn:org.opendaylight.sxp/features-sxp//xml/features,
 190                 mvn:org.opendaylight.tsdr/features-tsdr//xml/features
 191             sm-features: >
 192                 odl-sxp-routing,
 193                 odl-tsdr-core,
 194                 odl-tsdr-openflow-statistics-collector,
 195                 odl-tsdr-netflow-statistics-collector
 196
 197    .. note:: If the feature version is not specified in the URL (see example above), Karaf will use
 198              the latest version (normally only one stored) in the the system folder.
 199
 200 #. Push changes to releng/builder and wait for patch verification and review.
 201
 202    Once the patch is merged your project will be tested in the distribution-sanity_.
 203
 204 Trigger distribution build
 205 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 206
 207 Once the project is in the distribution it is recommended to build and publish a new distribution
 208 every time a merge happens in the project. Follow the steps below to add this trigger:
 209
 210 #. Download releng/builder repository:
 211
 212    .. code-block:: bash
 213
 214       git clone ssh://<user>@git.opendaylight.org:29418/releng/builder
 215
 216 #. Open the distribution-jobs.yaml file:
 217
 218    .. code-block:: bash
 219
 220       jjb/integration/distribution/distribution-jobs.yaml
 221
 222    And add your merge job in the distribution-full section:
 223
 224    .. code-block:: bash
 225
 226       - project:
 227           name: distribution-full
 228           ...
 229           stream:
 230             - fluorine:
 231                 branch: 'master'
 232                 dependencies: >
 233                     sxp-merge-{stream},
 234            ...
 235
 236 #. Push changes to releng/builder and wait for patch verification and review.
 237
 238 .. _managed-distribution: https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/integration/karaf
 239 .. _full-distribution: https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/integration/opendaylight
 240 .. _distribution-sanity: https://jenkins.opendaylight.org/releng/view/Sanity