Fix various minor issues in RPM docs

Change-Id: Ib64063dda234f4599b5ee2d77d778150d6699bd4
Signed-off-by: Daniel Farrell <dfarrell@redhat.com>

diff --git a/rpm/README.markdown b/rpm/README.markdown
index fd097e88b61d44c7416e24f717db7c19761b1406..d6658f59cc6b3f8b4bdcab1e4fc06f72d132526c 100644 (file)
--- a/rpm/README.markdown
+++ b/rpm/README.markdown
@@ -16,7 +16,7 @@ When new builds are defined, the new SRPMs are uploaded to the CentOS
 Community Build System's Koji-based RPM build system. From there they are
 built into ready-to-install noarch RPMs and hosted for consumption.
 
-Data that differs per-build is is defined in the `build_vars.yaml" YAML
+Data that differs per-build is is defined in the `build_vars.yaml` YAML
 configuration file. The build logic consumes that dynamic data, uses
 JinJa2 templates to generate RPM spec files and builds the RPMs/SRPMs they
 define.
@@ -87,7 +87,7 @@ version, there will be one or more major.minor.patch-rpm_release RPMs.
 Override build VM's disttag from `.el7.centos` to `.el7` per [expected norms][11].
 
 By default, the disttag RPM macro is determined at RPM build time by the
-rpmbuild tool. For our CentOS 7 Vagrantfile, this results in a disttag of
+`rpmbuild` tool. For our CentOS 7 Vagrantfile, this results in a disttag of
 `.el7.centos`. However, especially since we generate noarch RPMs, there's no
 technical reason to use `.el7.centos` instead of the more common `.el7` disttag.
 Per [recommendations from upstream CentOS packagers][11], seemingly mostly to
@@ -107,8 +107,8 @@ For example: `>= 1:1.7.0`
 Version of ODL systemd unitfile to download and package in ODL RPM.
 
 The version of OpenDaylight's systemd unitfile in the `packaging/rpm/unitfiles`
-directory specified by this git commit hash is downloaded from the Int/Pack
-repo and consumed by OpenDaylight's RPM builds as an RPM spec file Source.
+directory specified by this git commit hash is downloaded from the [Int/Pack
+repo][16] and consumed by OpenDaylight's RPM builds as an RPM spec file Source.
 
 #### `codename`
 
@@ -156,7 +156,7 @@ optional arguments:
 ```
 
 The `-v`/`--version` flag accepts a version number. Any build that matches
-the portions provided will be build. If more than one build matches the
+the portions provided will be built. If more than one build matches the
 portions provided, all matching builds will be executed.
 
 For example, `build.py -v 3` would execute the builds that match the regex
@@ -184,7 +184,7 @@ The familiar RPM-related commands apply to the OpenDaylight RPM.
 
 ### Installing OpenDaylight via a local RPM
 
-To install a local OpenDaylight's RPM, perhaps as a sanity check after a
+To install a local OpenDaylight RPM, perhaps as a sanity check after a
 build, use `sudo yum install -y <path to ODL RPM>`.
 
 Here's a walk-through of an install and the resulting system changes.
@@ -321,7 +321,7 @@ the [Quickstart section of the CBS docs][5].
 
 As noted in those docs, you'll need to get the SIG chair to leave a note
 on your bug to verify that you should have access. Dave Neary is the
-current NFV SIG chair. The Int/Pack PTL (currently [Daniel Farrell][6])
+current NFV SIG chair. The [Int/Pack][15] PTL (currently [Daniel Farrell][6])
 can help you get his cooperation.
 
 ### Using the CBS
@@ -405,7 +405,7 @@ the sections above document _how_.
 Typically, RPM builds use the macro mechanism provided by RPM spec files
 and the `rpmbuild` tool to customize specs for specific builds. This works
 well for default macros that are gathered from the system automatically, like
-disttag and unitdir.
+`disttag` and `unitdir`.
 
 However, once we needed to support multiple RPM builds at the same time, we
 needed to either accept a large amount of logic duplication or use custom
@@ -421,10 +421,12 @@ second RPM is an unacceptable increase in complexity, and it's unclear if
 Koji handles macro RPMs correctly anyway (potentially buggy, at least very
 infrequently used).
 
-Given the inability to define handle dynamic, custom macros in Koji-based
-builds, but the need to use custom macros to avoid an exceptional amount of
-duplicated logic, the macro substitution into of dynamic per-build data +
-templates into static (or at least no-custom-macros) RPM spec files emerged.
+Given this inability to define dynamic, custom macros in Koji-based builds,
+but the need to extract variables to avoid manual duplication of a large
+amount of spec file logic, a design that uses dynamic per-build data +
+templates to build simi-static (only default macros) RPM spec files emerged.
+The specifics (YAML, Python, JinJa2) were chosen because of their use in
+other tools used by [Int/Pack][15], like Packer, Ansible and Puppet.
 
 
 [1]: http://cbs.centos.org/koji/
@@ -441,3 +443,5 @@ templates into static (or at least no-custom-macros) RPM spec files emerged.
 [12]: https://wiki.opendaylight.org/view/Simultaneous_Release:Helium_Release_Plan#Schedule
 [13]: https://wiki.opendaylight.org/view/Simultaneous_Release:Lithium_Release_Plan#Schedule
 [14]: https://wiki.opendaylight.org/view/Simultaneous_Release:Beryllium_Release_Plan#Schedule
+[15]: https://wiki.opendaylight.org/view/Integration/Packaging
+[16]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging.git;a=tree;h=refs/heads/master;hb=refs/heads/master

diff --git a/rpm/build.py b/rpm/build.py
index a919b282d01d97d44768bb6440a13c54624f2c60..a264d1eb38e9310a109a60ed14831fe9619c90bd 100755 (executable)
--- a/rpm/build.py
+++ b/rpm/build.py
@@ -44,7 +44,7 @@ srpm_template = Template("opendaylight-$version_major.$version_minor."
 def build_rpm(build):
     """Build the RPMs described by the given build description.
 
-    :param build: Description of an RPM build, typically from rpm_vars.yaml
+    :param build: Description of an RPM build, typically from build_vars.yaml
     :type build: dict
 
     """

diff --git a/rpm/cache/cache.py b/rpm/cache/cache.py
index 52b0a26c04c9028b8c832f3f444c8af90516ad37..8334d5733c276c66e5b1a83c062983afe46f390e 100755 (executable)
--- a/rpm/cache/cache.py
+++ b/rpm/cache/cache.py
@@ -36,7 +36,7 @@ unitfile_tb_template = Template("opendaylight-$sysd_commit.service.tar.gz")
 def cache_build(build):
     """Cache the artifacts required for the given RPM build.
 
-    :param build: Description of an RPM build, typically from rpm_vars.yaml
+    :param build: Description of an RPM build, typically from build_vars.yaml
     :type build: dict
 
     """

diff --git a/rpm/specs/build_specs.py b/rpm/specs/build_specs.py
index 970a810177687c7c4bf4e766cfa36ff5369ab577..552ab14902c5cb2838902d0a1d17e5e56c7c8972 100755 (executable)
--- a/rpm/specs/build_specs.py
+++ b/rpm/specs/build_specs.py
@@ -30,7 +30,7 @@ specfile_template = Template("opendaylight-$version_major.$version_minor."
 def build_spec(build):
     """Build the RPM .spec file from a template for the given build description.
 
-    :param build: Description of an RPM build, typically from rpm_vars.yaml
+    :param build: Description of an RPM build, typically from build_vars.yaml
     :type build: dict
 
     """
@@ -44,7 +44,7 @@ def build_spec(build):
 if __name__ == "__main__":
     # Load RPM build variables from a YAML config file
     with open(os.path.join(spec_dir, os.pardir, "build_vars.yaml")) as var_fd:
-        rpm_vars = yaml.load(var_fd)
+        build_vars = yaml.load(var_fd)
 
-    for build in rpm_vars["builds"]:
+    for build in build_vars["builds"]:
         build_spec(build)