Add .rst files for readthedocs for Int/Pack

Change-Id: I37fa9706c36b57b8cb0118e2abed0b4c2369d073
Signed-off-by: Umesh Singla <umeshksingla@gmail.com>

diff --git a/docs/autorelease-builds.rst b/docs/autorelease-builds.rst
new file mode 100644 (file)
index 0000000..1d64dcb
--- /dev/null
+++ b/docs/autorelease-builds.rst
@@ -0,0 +1,86 @@
+Autorelease Builds
+==================
+
+OpenDaylight's primary build pipeline is called "autorelease". It is managed by
+the `RelEng/Autorelease`_ project, and primarily takes the form of
+`Autorelease's Jenkins jobs`_.
+
+Autorelease builds every project from source. There are jobs for each current
+OpenDaylight release, as well as the version under development.
+
+
+Daily Releases
+--------------
+
+`Autorelease's Jenkins jobs`_ run daily for every active branch, including
+master.
+
+- `Beryllium autorelease job`_
+- `Boron autorelease job`_
+- `Carbon autorelease job`_
+
+Each of those jobs, when the build is successful, produces build artifacts that
+include an OpenDaylight distribution. To download the distribution, pick an
+autorelease job that completed successfully (yellow or blue dot) and access its
+logged console output. Logs are hosted on logs.opendaylight.org, at URLs like
+`https://logs.opendaylight.org/releng/jenkins092/autorelease-release-<stream>/
+<build_number>/`, where stream could be "boron" build_number "228". There will
+be a link at the top of build's Jenkins page. Open `console.log.gz` in browser
+and search for "staging repository with ID". Find the repositoiry ID, which
+will be of the form "autorelease-1432". Navigate to `OpenDaylight's Nexus`_ and
+find the staging repository with the same name. Drill down into the directory
+tree org/opendaylight/integration/distribution-karaf/ to find the `build
+artifacts`_. Autorelease build artifacts are persevered for 60 days.
+
+Autorelease jobs trigger OpenDaylight's distribution tests when they complete.
+To see the test results, go to integration-distribution-test-<branch> job's
+Jenkins page, find the job that started after the autorelease in question
+finished. Open it and explore `Subprojects` section for test results of all
+the jobs triggered. For example, in case of Boron, you can find the list and
+the results of jobs triggered `here`_.
+
+The OpenDaylight Integration/Test project recently audited all tests to remove
+false negatives that were cluttering this report with failures that didn't
+imply a problem with OpenDaylight, but with test logic. If there are failures,
+especially new ones, pay attention to which OpenDaylight features they affect.
+If you don't load that Karaf feature, it shouldn't be relevant to you.
+
+The latest successful autorelease builds can also be easily found by using the
+`staging/org/opendaylight/integration/distribution-karaf/`_
+and look for 0.4.5-Beryllium-SR5, 0.5.3-Boron-SR3 or 0.6.0-Carbon or similar
+staging repositories. However, the artifacts in these repositories are not
+static - they are replaced each time new artifacts are generated. Use the
+"autorelease-XXXX" repositories described above for semi-persistent URLs.
+
+
+Official Releases
+-----------------
+
+As a part of the OpenDaylight community's efforts to move towards Continuous
+Delivery, there is very little mechanical difference between the automated
+daily releases documented above and official releases. The same autorelease
+job runs, builds artifacts and kicks off distribution tests against them. When
+doing official releases, the OpenDaylight community iterates through those
+builds (calling them Release Candidate 1, RC2, ...) until no blocking bugs are
+found. The OpenDaylight Technical Steering Committee then hears feedback from
+the Release Engineering and Integration/Test teams, and if all's well blesses
+the build as an official release. The build's Nexus staging repo is then
+promoted to a release repo and publicized (example: `opendaylight.release/org
+/opendaylight/integration/distribution-karaf/0.5.2-Boron-SR2`_). Official
+releases are persevered forever.
+
+For more information about OpenDaylight releases, including timelines, see the
+`Release Plans`_.
+
+
+.. _RelEng/Autorelease: https://git.opendaylight.org/gerrit/gitweb?p=releng/autorelease.git;a=tree;h=refs/heads/master;hb=refs/heads/master
+.. _Autorelease's Jenkins jobs: https://jenkins.opendaylight.org/releng/view/autorelease/
+.. _Beryllium autorelease job: https://jenkins.opendaylight.org/releng/view/autorelease/job/autorelease-release-beryllium/
+.. _Boron autorelease job: https://jenkins.opendaylight.org/releng/view/autorelease/job/autorelease-release-boron/
+.. _Carbon autorelease job: https://jenkins.opendaylight.org/releng/view/autorelease/job/autorelease-release-carbon/
+.. _OpenDaylight's Nexus: https://nexus.opendaylight.org/content/repositories/
+.. _build artifacts: https://nexus.opendaylight.org/content/repositories/autorelease-1432/org/opendaylight/integration/distribution-karaf/0.5.0-Boron-RC1/
+.. _here: https://jenkins.opendaylight.org/releng/job/integration-distribution-test-boron/
+.. _staging/org/opendaylight/integration/distribution-karaf/: https://nexus.opendaylight.org/content/repositories/staging/org/opendaylight/integration/distribution-karaf/
+.. _opendaylight.release/org /opendaylight/integration/distribution-karaf/0.5.2-Boron-SR2: https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/integration/distribution-karaf/0.5.2-Boron-SR2/
+.. _Release Plans: https://wiki.opendaylight.org/view/Release_Plan

diff --git a/docs/debs.rst b/docs/debs.rst
new file mode 100644 (file)
index 0000000..120d60f
--- /dev/null
+++ b/docs/debs.rst
@@ -0,0 +1,23 @@
+Debs
+====
+
+The `build.py`_ helper script is used for building OpenDaylight .debs. It can
+build a set of .debs based on provided version arguments. The dynamic aspects
+of builds, such as ODL and deb version info, have all been extracted to single
+YAML configuration file.
+
+The variables available for configuration and instructions on how to install
+are documented `here`_.
+
+
+Build Deb Job
+--------------
+
+The Jenkins `build_deb job`_ builds the .deb package described by the `given
+build description`_, using build.py inside the deb directory.
+
+
+.. _build.py: https://github.com/opendaylight/integration-packaging/blob/master/deb/build.py
+.. _here: https://github.com/opendaylight/integration-packaging/blob/master/deb/README.markdown
+.. _build_deb job: https://jenkins.opendaylight.org/releng/job/packaging-build-deb-master/
+.. _given build description: https://jenkins.opendaylight.org/releng/job/packaging-build-deb-master/build?delay=0sec

diff --git a/docs/distribution-job-builds.rst b/docs/distribution-job-builds.rst
new file mode 100644 (file)
index 0000000..30644b6
--- /dev/null
+++ b/docs/distribution-job-builds.rst
@@ -0,0 +1,46 @@
+Distribution Job Builds
+=======================
+
+Unlike autorelease builds, which build every project from source, distribution
+jobs only build a few Karaf features. This makes them much quicker (minutes
+instead of ~11 hours), and therefore suitable for CI testing. End-users like
+OPNFV should stick with autorelease jobs.
+
+
+Snapshot Builds
+---------------
+
+Distribution job builds are typically kicked off when a patch is merged into
+a project. Projects define `<project>`-merge-<branch> Jenkins jobs, which are
+kicked off by a Gerrit merge events. To find the merge job for a Gerrit, look
+for comments from the jenkins-releng user like "Build Started
+https://jenkins.opendaylight.org/releng/job/netvirt-merge-boron/216/".
+
+Alternatively, browse a project's Jenkins tab and look at the recent runs.
+For example, go to https://jenkins.opendaylight.org/releng/, select Merge-Boron
+and you'll find the list of all projects merge jobs in the format
+`<project>`-merge-boron. Click any to view the recent build job details and
+logs.
+
+For each active branch, snapshot builds created by distribution jobs can be
+found in the subdirs at `opendaylight.snapshot/org/opendaylight/integration
+/distribution-karaf/`_. The maven-metadata.xml tells about the different
+versions and the latest one. The different subdirectories (say, 0.5.2-SNAPSHOT)
+contain all the corresponding version (0.5.2 here) builds stored by time (time
+included in the artifact name).
+
+Recent build artifacts info for a given branch can be found in the XML's
+`<content-item>` at `opendaylight.snapshot/content/org/opendaylight/integration
+/distribution-karaf/`_.
+
+
+Custom Distributions
+--------------------
+
+Distributions can be built with an additional set of unmerged patches. `See
+this wiki`_.
+
+
+.. _opendaylight.snapshot/org/opendaylight/integration /distribution-karaf/: https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/integration/distribution-karaf/
+.. _opendaylight.snapshot/content/org/opendaylight/integration /distribution-karaf/: https://nexus.opendaylight.org/service/local/repositories/opendaylight.snapshot/content/org/opendaylight/integration/distribution-karaf/
+.. _See this wiki: https://wiki.opendaylight.org/view/Integration/Test/Running_System_Tests#Running_System_Tests_Using_Custom_Distribution_Built_From_Multiple_Patches

diff --git a/docs/index.rst b/docs/index.rst
index 18e1347a39bf9c71e55329937720f731617c14dd..e21872871a2782b5255b5ab79a5b0de1e5e6ee5b 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,3 +15,6 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   autorelease-builds
+   distribution-job-builds
+   packages

diff --git a/docs/packages.rst b/docs/packages.rst
new file mode 100644 (file)
index 0000000..c2085f1
--- /dev/null
+++ b/docs/packages.rst
@@ -0,0 +1,11 @@
+Packages
+========
+
+Some builds are packaged as RPMs or .debs for easy consumption by downstream
+users.
+
+.. toctree::
+   :maxdepth: 2
+
+   rpms
+   debs

diff --git a/docs/rpms.rst b/docs/rpms.rst
new file mode 100644 (file)
index 0000000..a36b93e
--- /dev/null
+++ b/docs/rpms.rst
@@ -0,0 +1,49 @@
+RPMs
+====
+
+
+Automated RPM Builds
+--------------------
+
+OpenDaylight Integration/Packaging has added support for many variations of
+fully automated RPM builds.
+
+
+Build RPM Job
+^^^^^^^^^^^^^
+
+The Jenkins `build_rpm job`_ builds an ODL RPM described by the `given Jenkins
+build parameters`_, using the `build.py`_ script.
+
+
+Build Latest Snapshot Job
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For a given major version, you can build an RPM from the latest snapshot by
+passing `- -build-latest-snap` to build.py.
+
+The Jenkins `build_rpm_snap job`_ builds the latest snapshot into RPM. It
+extracts ODL version info from the artifact's URL to build artifacts. The
+necessary JJB params to pass are OpenDaylight's major and minor version to
+build, sysd_commit (version of ODL systemd unitfile to download and package
+in RPM), changelog name and email.
+
+
+CentOS CBS RPMs
+---------------
+
+OpenDaylight's RPMs are built and hosted on the CentOS Community Build System's
+Koji build servers.
+
+All OpenDaylight RPMs, and the SRPMs with tarballs from the builds described
+previously, are permanently available for download `here`_.
+
+See the `Deployment#RPM`_ wiki for more information about RPMs.
+
+
+.. _build_rpm job: https://jenkins.opendaylight.org/releng/job/packaging-build-rpm-master/
+.. _given Jenkins build parameters: https://jenkins.opendaylight.org/releng/job/packaging-build-rpm-master/build?delay=0sec
+.. _build.py: https://github.com/opendaylight/integration-packaging/blob/master/rpm/build.py
+.. _build_rpm_snap job: https://jenkins.opendaylight.org/releng/job/packaging-build-rpm-snap-master/
+.. _here: http://cbs.centos.org/koji/packageinfo?packageID=755
+.. _Deployment#RPM: https://wiki.opendaylight.org/view/Deployment#RPM