Fixed several sphinx WARNINGS, added more release text
Change-Id: Ia167a9d46ee48fbf27c6cd09d78fcf31f3d4aedf
diff --git a/Makefile b/Makefile
index 3de80c0..7b62057 100644
--- a/Makefile
+++ b/Makefile
@@ -194,15 +194,32 @@
## Intent: Display WARNINGS buried in sphinx output
## -----------------------------------------------------------------------
warnings-log := warnings.log
-warnings:
+warnings: sterile
$(MAKE) html 2>&1 \
| sed -e 's@\([Ww][Aa][Rr][Nn][Ii][Nn][Gg]\)@\n\1@g' \
> "$(warnings-log)"
- less --ignore-case --hilite-search --pattern='/warning' $(warnings-log)
+ grep 'WARNING' $(warnings-log)
+## -----------------------------------------------------------------------
+## Intent: Summarize linkcheck failures
+## -----------------------------------------------------------------------
+.PHONY: broken-log
+broken-log := broken.log
+broken-log : sterile
+ $(MAKE) linkcheck 2>&1 | tee "$(broken-log)"
+ ! grep broken "$(broken-log)"
+ grep -i error _build/linkcheck/output.txt
+
+## -----------------------------------------------------------------------
+## Intent:
+## -----------------------------------------------------------------------
clean::
+ $(RM) $(broken-log)
$(RM) $(warnings-log)
+## -----------------------------------------------------------------------
+## Intent:
+## -----------------------------------------------------------------------
help ::
@echo " warnings Display WARNING strings buried in sphinx output"
diff --git a/VERSION b/VERSION
index 56beced..faad078 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.12.4
+2.12.4.1
diff --git a/conf.py b/conf.py
index 9290b6f..94eacfa 100644
--- a/conf.py
+++ b/conf.py
@@ -140,6 +140,7 @@
'CODE_OF_CONDUCT.md',
'*/CODE_OF_CONDUCT.md',
# Ignore all:
+ 'makefiles',
'__pycache__',
'**/__pycache__', # generated - faster traversal
'.venv',
diff --git a/howto/release/checklist.rst b/howto/release/checklist.rst
index 1ad638a..82427b9 100644
--- a/howto/release/checklist.rst
+++ b/howto/release/checklist.rst
@@ -23,19 +23,34 @@
Packages
--------
+
- Package `aaa <https://gerrit.opencord.org/c/aaa/+/33599>`_
+
- Versions
+
- New
- Old
+
- DEPS: sadis
- Package `sadis <https://gerrit.opencord.org/plugins/gitiles/sadis/>`_
+
- Versions
+
- `New: 5.11.0-SNAPSHOT <https://gerrit.opencord.org/plugins/gitiles/sadis/+/refs/heads/master/pom.xml#30>`_
- `Old: (5.10.0) <https://central.sonatype.com/artifact/org.opencord/sadis/5.10.0?smo=true>`_
+
- DEPS:
-
-
+
+TST(s)
+------
+
+- Verify the list of TST members are correct on
+
+ - `ONF Website <https://opennetworking.org/voltha/>`_
+ - `Wiki <https://wiki.opennetworking.org/display/COM/VOLTHA>`_
+ - `Release Notes <https://docs.voltha.org/master/release_notes/index.html>`_
+
Release Notes
-------------
diff --git a/howto/release/ci-management/clone_testing.rst b/howto/release/ci-management/clone_testing.rst
index 74e9a86..e45c92f 100644
--- a/howto/release/ci-management/clone_testing.rst
+++ b/howto/release/ci-management/clone_testing.rst
@@ -12,11 +12,11 @@
on a seprate branch within revision control. Instead versioning is
implemented using naming conventions within the job configs.
-WIP:
+WIP:
----
- Clone the ci-management repository
- - git clone ssh://gerrit.opencord.org:29418/ci-management.git
+ - git clone ssh://gerrit.opencord.org:29418/ci-management.git
TODO
diff --git a/howto/release/ci-management/index.rst b/howto/release/ci-management/index.rst
index 5992fc5..d812ab8 100644
--- a/howto/release/ci-management/index.rst
+++ b/howto/release/ci-management/index.rst
@@ -12,3 +12,5 @@
clone_and_branch_testing
create_lts_view
jjb_software_upgrades
+
+ clone_testing
diff --git a/howto/release/components/onos_components.rst b/howto/release/components/onos_components.rst
index cc2af3c..bf4fb82 100644
--- a/howto/release/components/onos_components.rst
+++ b/howto/release/components/onos_components.rst
@@ -45,12 +45,19 @@
- master (?)
- - Jenkins jobs from `release matrix: v2.12 <https://wiki.opennetworking.org/display/VOLTHA/v2.12+-+Jenkins+jobs+and+failures>`_
- - `changeset approval for job merge<https://gerrit.opencord.org/q/owner:do-not-reply%2540opennetworking.org>`_
+Jenkins Jobs
+^^^^^^^^^^^^
+
+- Jenkins jobs from `release matrix: v2.12 <https://wiki.opennetworking.org/display/VOLTHA/v2.12+-+Jenkins+jobs+and+failures>`_
+
+ - `changeset approval for job merge <https://gerrit.opencord.org/q/owner:do-not-reply%2540opennetworking.org>`_
- pom.xml non-SNAPSHOT (first approved changeset)
+
- `licensed <https://jenkins.opencord.org/job/verify_sadis_licensed/>`_
- `verify <https://jenkins.opencord.org/job/verify_sadis_maven-test/>`_
+
- pom.xml non-SNAPSHOT (second approved changeset)
+
- `publish <https://jenkins.opencord.org/job/maven-publish_sadis/>`_
- Job will modify pom.xml and create pull requests based on version strings.
diff --git a/howto/release/components/onos_dependencies.rst b/howto/release/components/onos_dependencies.rst
index 5068cd3..5d54fb4 100644
--- a/howto/release/components/onos_dependencies.rst
+++ b/howto/release/components/onos_dependencies.rst
@@ -8,27 +8,47 @@
- Three jenkins jobs
- - modify version in pom.xml for release (remove -SNAPSHOT)
- - publish artifact to maven central.
- - modify version in pom.xml for release (append -SNAPSHOT)
+ - modify version in pom.xml for release (remove -SNAPSHOT) for release.
+ - publish artifact to Maven Central.
+ - modify version in pom.xml for release (append -SNAPSHOT) for development.
- - Three manual operations:
+ - Four manual operations:
- Review and approve pull request to create a pom.xml release version.
+ - Stage Maven Central deployment on a Nexus server.
- Release artifact to maven central.
- Review and approve pull request to create a pom.xml non-release version.
- - Long idle window(s)
+ - Long idle window(s): some 10 hours or more.
First submit nop jobs to verify the packages can build and test cleanly.
Bulk update copyright notice dates or modify comments within sources and submit.
+Once pakges build and test clenaly initiate a release job.
Search pom.xml for package version string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-component sadis
+.. list-table:: Semantic Version Strings
+ :header-rows: 1
+ :widths: 20,5,50
-Package version strings should contain the suffix -SNAPSHOT.
+ * - Version
+ - Published
+ - Description
+ * - 5.11.0-SNAPSHOT
+ - No
+ - Development version string
+ * - 5.11.0
+ - Yes
+ - Production version string
+
+Component: pom.xml
+------------------
+
+Verify package and package.api version string state
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Prior to release suffix-SNAPSHOT will be visible.
.. code:: bash
@@ -47,10 +67,11 @@
</properties>
-Next search pom.xml for dependent packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Update dependent components, apis, ...
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
component: aaa
+dependency: sadis
Dependent package version strings will be a released (non-SNAPSHOT) version.
@@ -61,6 +82,37 @@
<aaa.api.version>2.8.0-SNAPSHOT</aaa.api.version>
</properties>
+Update Maven plugin versions for security, bugs, logs, etc
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code:: XML
+
+ <!-- SpotBugs Static Analysis -->
+ <plugin>
+ <groupId>com.github.spotbugs</groupId>
+ <artifactId>spotbugs-maven-plugin</artifactId>
+ <version>4.7.3.4</version>
+ </plugin>
+
+ <plugin>
+ <groupId>com.h3xstream.findsecbugs</groupId>
+ <artifactId>findsecbugs-plugin</artifactId>
+ <version>1.12.0</version>
+ </plugin>
+
+Update copyright notice to be inclusive of the year last modified
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`Copyright notice syntax <https://github.com/joey-onf/copyright>`_
+
+.. code:: XML
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!--
+ ~ Copyright 2017-2023 Open Networking Foundation (ONF) and the ONF Contributors
+ ~
+ ~ Licensed under the Apache License, Version 2.0 (the "License");
+ -->
+
Dependency Hierarchy
--------------------
@@ -160,3 +212,29 @@
segmentrouting
^^^^^^^^^^^^^^
+
+
+Validate release(d) version information
+---------------------------------------
+
+- Visit Maven Central.
+- Sanity check deployed pom.xml files contain correct
+
+ - Package and api versions.
+ - ONOS package version
+ - Dependent package version.
+
+- Yes an automation script should be created for this task.
+- A jenkins job can be run post deployment to perform validation.
+
+ - Input would be a config file containing expected versions.
+ - For complete coverage the job could be run:
+
+ - pre-release: validate incoming SNAPSHOT version(s).
+ - post-release: verify deployed artifact and pom.xml versions.
+ - post-validation: jenkins would increment expected versions.
+
+- TODO: Start by creating a config file populated with version strings.
+
+ - Static text can be used to maintain docs.voltha.org/release_notes/
+ - Config would also be used as input to voltha-release (hardcoded values).
diff --git a/howto/release/index.rst b/howto/release/index.rst
index ce276ee..e1d998c 100644
--- a/howto/release/index.rst
+++ b/howto/release/index.rst
@@ -20,3 +20,7 @@
voltctl/install
voltctl/release
voltctl/see_also
+
+ checklist
+ scripts/preparation
+ scripts/repository-voltha-release
diff --git a/howto/release/scripts/preparation.rst b/howto/release/scripts/preparation.rst
new file mode 100644
index 0000000..fb6de71
--- /dev/null
+++ b/howto/release/scripts/preparation.rst
@@ -0,0 +1,17 @@
+Release Utilities
+=================
+
+Known Issues
+------------
+.. list-table:: Helper Scripts
+ :widths: 10, 40
+ :header-rows: 1
+
+ * - Resource
+ - Description
+ * - `repo:voltha-release <https://github.com/joey-onf/voltha-release>`_
+ - Validate code base dependencies and versiosn for a VOLTHA release.
+ * - `repo:voltha-release/validate <https://github.com/joey-onf/voltha-release/tree/origin/master/validate>`_
+ - Early shell script version of voltha-release.
+ * - `repo:onf-release <https://github.com/joey-onf/onf-release>`_
+ - repo:onf-release
diff --git a/howto/release/scripts/repository-voltha-release.rst b/howto/release/scripts/repository-voltha-release.rst
new file mode 100644
index 0000000..914f86b
--- /dev/null
+++ b/howto/release/scripts/repository-voltha-release.rst
@@ -0,0 +1,15 @@
+Release Utilities
+=================
+
+Known Issues
+------------
+.. list-table:: Helper Scripts
+ :widths: 10, 40
+ :header-rows: 1
+
+ * - Resource
+ - Description
+ * - `repo:voltha-release <https://github.com/joey-onf/voltha-release>`_
+ - Repository containing release related tools.
+ * - `repo:onf-release <https://github.com/joey-onf/onf-release>`_
+ - Validate code base dependencies and versiosn for a VOLTHA release.