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 #. Add your feature repo and user-facing features in:
 174
 175    .. code-block:: bash
 176
 177       jjb/integration/distribution/distribution-jobs.yaml
 178
 179    See this example for the file section:
 180
 181    .. code-block:: bash
 182
 183       # Self-Managed projects features
 184       sm-repos: >
 185           mvn:org.opendaylight.sxp/features-sxp//xml/features
 186
 187       sm-features: >
 188           odl-sxp-controller
 189
 190    .. note:: If the feature version is not specified in the URL (see example above), Karaf will use
 191              the latest version (normally only one stored) in the the system folder.
 192
 193 #. Push changes to releng/builder and wait for patch verification and review.
 194
 195    Once the patch is merged your project will be tested in the distribution-sanity_.
 196
 197 Trigger distribution build
 198 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 199
 200 Once the project is in the distribution it is recommended to build and publish a new distribution
 201 every time a merge happens in the project. Follow the steps below to add this trigger:
 202
 203 #. Download releng/builder repository:
 204
 205    .. code-block:: bash
 206
 207       git clone ssh://<user>@git.opendaylight.org:29418/releng/builder
 208
 209 #. Open the distribution-jobs.yaml file:
 210
 211    .. code-block:: bash
 212
 213       jjb/integration/distribution/distribution-jobs.yaml
 214
 215    And add your merge job in the distribution-full section:
 216
 217    .. code-block:: bash
 218
 219       - project:
 220           name: distribution-full
 221           ...
 222           stream:
 223             - fluorine:
 224                 branch: 'master'
 225                 dependencies: >
 226                     sxp-merge-{stream},
 227            ...
 228
 229 #. Push changes to releng/builder and wait for patch verification and review.
 230
 231 .. _managed-distribution: https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/integration/karaf
 232 .. _full-distribution: https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/integration/opendaylight
 233 .. _distribution-sanity: https://jenkins.opendaylight.org/releng/view/Sanity