From ba622e0a953186619c5604c7ecb41410476b3ba8 Mon Sep 17 00:00:00 2001 From: Umesh Singla Date: Thu, 22 Dec 2016 04:37:09 +0530 Subject: [PATCH] Add .rst files for readthedocs for Int/Pack Change-Id: I37fa9706c36b57b8cb0118e2abed0b4c2369d073 Signed-off-by: Umesh Singla --- docs/autorelease-builds.rst | 86 ++++++++++++++++++++++++++++++++ docs/debs.rst | 23 +++++++++ docs/distribution-job-builds.rst | 46 +++++++++++++++++ docs/index.rst | 3 ++ docs/packages.rst | 11 ++++ docs/rpms.rst | 49 ++++++++++++++++++ 6 files changed, 218 insertions(+) create mode 100644 docs/autorelease-builds.rst create mode 100644 docs/debs.rst create mode 100644 docs/distribution-job-builds.rst create mode 100644 docs/packages.rst create mode 100644 docs/rpms.rst diff --git a/docs/autorelease-builds.rst b/docs/autorelease-builds.rst new file mode 100644 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-/ +/`, 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- 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 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 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 ``-merge- 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 +``-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 +`` 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 18e1347..e218728 100644 --- 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 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 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 -- 2.36.6