Document fixes for lint errors
howto/code/lint/index.rst
howto/code/lint/fix-errors
--------------------------
o Added a new 'fixing-errors' section in 'howto: lint'.
howto/code/lint/fix-errors/sphinx/spelling
howto/code/lint/fix-errors/yamllint
------------------------------------------
o Document a few known fixes for common problems.
requirements.txt
----------------
o Capture detail for a python upgrade error uncovered by 'make reload'.
o libdoc command for robot/robotframework having issues.
Change-Id: Iaa700327d374b6040841cbfc98f76ba95c16c799
Signed-off-by: Joey Armstrong <jarmstrong@linuxfoundation.org>
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 5a66739..b9bf768 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,13 +1,23 @@
---
# -----------------------------------------------------------------------
+# [NOTE] - Propogate .pre-commit-config.yaml edits to all repositories!
+# -----------------------------------------------------------------------
+# [TODO]
+# - pre-commit yaml config exists individually within repositories.
+# - Generally lint config and benavior is consistent for all repos.
+# - Exclusions and bulk cleanup necessitate per-repo custom configs.
+# - Dynamically generate this config file from common and custom
+# -----------------------------------------------------------------------
+
+# -----------------------------------------------------------------------
# Copyright 2024 Open Networking Foundation Contributors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
-# http:#www.apache.org/licenses/LICENSE-2.0
+# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
@@ -21,39 +31,59 @@
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
# -----------------------------------------------------------------------
-# .pre-commiit-config-yaml v0.1
+# .pre-commit-config-yaml 2024-04-10 v0.3
# -----------------------------------------------------------------------
+# ci:
+# skip: [sync]
+
repos:
-- repo: https://github.com/pre-commit/pre-commit-hooks
+ # Sync from repo
+ - repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
-- repo: https://github.com/koalaman/shellcheck-precommit
+
+ - repo: https://github.com/koalaman/shellcheck-precommit
rev: v0.10.0
hooks:
- id: shellcheck
-- repo: https://github.com/adrienverge/yamllint.git
+
+ - repo: https://github.com/adrienverge/yamllint.git
rev: v1.35.1
hooks:
- id: yamllint
## -----------------------------------------------------------------------
+## [SOURCE] REUSE License Checking
+## -----------------------------------------------------------------------
+# - repo: https://github.com/ansys/pre-commit-hooks
+# rev: v0.2.9
+# hooks:
+# - id: add-license-headers
+# args:
+# - --custom_copyright=custom copyright phrase
+# - --custom_template=template_name
+# - --custom_license=license_name
+# - --ignore_license_check
+# - --start_year=2023
+
+## -----------------------------------------------------------------------
## [SOURCE] Python
## -----------------------------------------------------------------------
-# - repo: https://github.com/psf/black
-# rev: 22.10.0
-# hooks:
-# - id: black
+# - repo: https://github.com/psf/black
+# rev: 22.10.0
+# hooks:
+# - id: black
-# - repo: https://github.com/PyCQA/doc8
-# rev: v1.1.1
-# hooks:
-# - id: doc8
-
+# - repo: https://github.com/PyCQA/doc8
+# rev: v1.1.1
+# hooks:
+# - id: doc8
+
# -------------------------------------------------------------------
# https://docs.python.org/3/library/re.html#regular-expression-syntax
# -------------------------------------------------------------------
@@ -63,14 +93,14 @@
^makefiles/.* |
^lf/.* |
^.venv/.* |
+ ^jenkins-scripts/.* |
+ ^lf-ansible/.* |
+ ^packer/.* |
+ ^test/.* |
+ ^jjb/pipeline/voltha/voltha-physical-soak-dt-tests.groovy
)$
# [SEE ALSO]
# -----------------------------------------------------------------------
-# https://github.com/memfault/interrupt/blob/master/example/pre-commit/.pre-commit-config.yaml
-# https://pre-commit.com/hooks.html
-# https://github.com/floatingpurr/sync_with_poetry/blob/main/.pre-commit-config.yaml
-# https://github.com/the-common/pre-commit-config-template/blob/master/.pre-commit-config.yaml
-# -----------------------------------------------------------------------
# [EOF]
diff --git a/VERSION b/VERSION
index 26340c0..a5c5ebd 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.12.36
+2.12.37
diff --git a/howto/code/lint/fix-errors/index.rst b/howto/code/lint/fix-errors/index.rst
new file mode 100644
index 0000000..e48d6a8
--- /dev/null
+++ b/howto/code/lint/fix-errors/index.rst
@@ -0,0 +1,8 @@
+LINT: Fixing errors
+=========================
+
+.. toctree::
+ :glob:
+
+ sphinx/spelling/*
+ yamllint/*
diff --git a/howto/code/lint/fix-errors/sphinx/spelling/index.rst b/howto/code/lint/fix-errors/sphinx/spelling/index.rst
new file mode 100644
index 0000000..fe040a5
--- /dev/null
+++ b/howto/code/lint/fix-errors/sphinx/spelling/index.rst
@@ -0,0 +1,7 @@
+LINT: Spelling Errors
+=====================
+
+.. toctree::
+ :maxdepth: 2
+
+ spelling-exclusions
diff --git a/howto/code/lint/fix-errors/sphinx/spelling/spelling-exclusions.rst b/howto/code/lint/fix-errors/sphinx/spelling/spelling-exclusions.rst
new file mode 100644
index 0000000..9051fbd
--- /dev/null
+++ b/howto/code/lint/fix-errors/sphinx/spelling/spelling-exclusions.rst
@@ -0,0 +1,31 @@
+LINT: Spelling exclusions
+=========================
+
+Correct spelling problems within docs whenever possible but on occasions
+when commands or error message strings are in the dictionary exclusions
+can be added
+
+.. code:: bash
+
+ % make spelling
+
+Spelling exclusion for a special string
+---------------------------------------
+
+- Ignore this `` :spelling:ignore:`bogus-word` ``
+- Quoting: ``item``
+
+Spelling exclusions by list
+---------------------------
+
+Exclude `foo, bar & tans` within a single document.
+.. code:: bash
+
+ `` .. spelling:: ``
+ foo
+ bar
+ tans
+
+.. seealso::
+
+ [managing-lists-of-correctly-spelled-words-and-ignoring-words](https://sphinxcontrib-spelling.readthedocs.io/en/latest/customize.html#managing-lists-of-correctly-spelled-words-and-ignoring-words)
diff --git a/howto/code/lint/fix-errors/yamllint/long-lines.rst b/howto/code/lint/fix-errors/yamllint/long-lines.rst
new file mode 100644
index 0000000..e4d16bf
--- /dev/null
+++ b/howto/code/lint/fix-errors/yamllint/long-lines.rst
@@ -0,0 +1,15 @@
+LINT: Spelling exclusions
+=========================
+
+.. code:: bash
+
+ % make lint-yaml
+
+Folding
+-------
+
+- >, >-, >+
+
+.. seealso::
+
+- https://yaml-multiline.info/
diff --git a/howto/code/lint/index.rst b/howto/code/lint/index.rst
index 0668a27..c061006 100644
--- a/howto/code/lint/index.rst
+++ b/howto/code/lint/index.rst
@@ -4,8 +4,8 @@
.. toctree::
:maxdepth: 1
- index.rst
lint-helm.rst
+ fix-errors
======================================
diff --git a/operations/software-upgrade.rst b/operations/software-upgrade.rst
index b125bb5..b7d27dc 100644
--- a/operations/software-upgrade.rst
+++ b/operations/software-upgrade.rst
@@ -2,33 +2,39 @@
VOLTHA and ONOS software update procedures
=============================================
-This document describes the software upgrade procedure for VOLTHA and ONOS in a deployed system.
-Distinction is made between a `minor` software upgrade, which can be done in service,
-meaning with no dataplane service interruption to existing customers, and a `major` software upgrade,
-which in turns requires a full maintenance window during which service is impacted.
+This document describes the software upgrade procedure for VOLTHA and ONOS
+in a deployed system. Distinction is made between a `minor` software upgrade,
+which can be done in service, meaning with no dataplane service interruption
+to existing customers, and a `major` software upgrade, which in turns requires
+a full maintenance window during which service is impacted.
-Changes to data-structures in storage (ETCD for VOLTHA and Atomix for ONOS) are out of scope for in-service upgrades.
-Such changes qualify as “major” software upgrades that require a maintenance windows.
-The KAFKA bus update has its own section given that the procedure is different from the rest of the components.
-The following elements expect a fully working provisioned VOLTHA and ONOS deployment on top of a Kubernetes cluster,
-with exposed ONOS REST API ports.
-It is also expected that new versions of the different components are available to the operator that performs
-the upgrade.
+Changes to data-structures in storage (ETCD for VOLTHA and Atomix for ONOS)
+are out of scope for in-service upgrades. Such changes qualify as “major”
+software upgrades that require a maintenance windows. The KAFKA bus update
+has its own section given that the procedure is different from the rest of
+the components. The following elements expect a fully working provisioned
+VOLTHA and ONOS deployment on top of a Kubernetes cluster, with exposed ONOS
+REST API ports. It is also expected that new versions of the different
+components are available to the operator that performs the upgrade.
Minor Software Version Update
=============================
-The `minor` software upgrade qualifier refers to an upgrade that does not involve API
-changes, which in VOLTHA, refers to either a change to the protos or to voltha-lib-go,
-and in ONOS to a change in the Java interfaces, CLI commands or REST APIs of either the Apps or the platform.
-A `minor` software update is intended for bug fixes and not for new features.
-`Minor` software update is supported only for ONOS apps and VOLTHA components. No in service software update
-is supported for ETCD or Kafka.
+
+The `minor` software upgrade qualifier refers to an upgrade that does not
+involve API changes, which in VOLTHA, refers to either a change to the protos
+or to voltha-lib-go, and in ONOS to a change in the Java interfaces, CLI
+commands or REST APIs of either the Apps or the platform. A `minor` software
+update is intended for bug fixes and not for new features. `Minor` software
+update is supported only for ONOS apps and VOLTHA components. No in service
+software update is supported for ETCD or Kafka.
VOLTHA services
---------------
+
VOLTHA components `minor` software upgrade leverages `helm` and `k8s`.
-During this process is expected that no provision subscriber call is executed from the northbound.
-In process calls will be executed thanks to the stored data and/or the persistence of messages over KAFKA.
+During this process is expected that no provision subscriber call is
+executed from the northbound. In process calls will be executed thanks to
+the stored data and/or the persistence of messages over KAFKA.
After changes in the code are made and verified the following steps are needed:
@@ -59,10 +65,12 @@
`mac-learning`, `igmpproxy`, and `mcast`. These apps can be thus updated with no impact on the dataplane of provisioned
subscribers. The `minor` software update for the ONOS apps leverage existing ONOS REST APIs.
-During this process is expected that no provision subscriber call is executed from the REST APIs.
-In process calls will be executed thanks to the Atomix stored flows.
-Some metrics and/or packet processing might be lost during this procedure, the system relies on retry mechanisms
-present in the services and the dataplane protocols for converging to a stable stated (e.g. DHCP retry)
+During this process is expected that no provision subscriber call is
+executed from the REST APIs. In process calls will be executed thanks to
+the Atomix stored flows. Some metrics and/or packet processing might be
+lost during this procedure, the system relies on retry mechanisms present in
+the services and the dataplane protocols for converging to a stable stated
+(e.g. DHCP retry).
After changes in the code of ONOS apps are made and verified the following steps are needed:
diff --git a/overview/release_process.rst b/overview/release_process.rst
index cfd6c22..1b687c1 100644
--- a/overview/release_process.rst
+++ b/overview/release_process.rst
@@ -104,7 +104,7 @@
that will publish an artifact into the staging repo on `sonatype <https://oss.sonatype.org>`_.
Once published to the staging server the artifact will need to be released to maven central.
- - Login into the sonatype server (for username and password contact michelle@opennetworking.org)
+ - Login into the sonatype server (for username and password contact mroth@linuxfoundation.org)
- search for org.opencord
- Select the app you want to release and click "all versions"
- Click on "Staging repositories" (in the left side navigation)
diff --git a/requirements.txt b/requirements.txt
index 56ea2f1..ec3428f 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -6,7 +6,7 @@
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
-# http:#www.apache.org/licenses/LICENSE-2.0
+# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
@@ -18,6 +18,7 @@
# SPDX-License-Identifier: Apache-2.0
# -----------------------------------------------------------------------
+
Sphinx~=4.1.2 # 2021-07-26
doc8~=0.9.0
docutils==0.16
@@ -27,18 +28,14 @@
sphinxcontrib-spelling~=7.2.1
git+https://github.com/zdw/sphinx-multiversion@ec7c01cdaf2f9241245e84483dfb9bc0d0dffc62
+#
sphinx-reload
##----------------##
##---] LINT [---##
##----------------##
pre-commit
-
-## ----------------------------------------------------
-## Bogus imports
-## ----------------------------------------------------
-## Implicit unused dependency -- requires Sphinx v5.0.2
-# sphinxcontrib-applehelp==1.0.8
+yamllint
# emacs .venv/lib/python3.10/site-packages/Sphinx-4.1.2.dist-info/METADATA
diff --git a/testing/certification.rst b/testing/certification.rst
index a32dbd5..35da407 100644
--- a/testing/certification.rst
+++ b/testing/certification.rst
@@ -5,21 +5,24 @@
VOLTHA is part fo the `continuous certification program at ONF <https://opennetworking.org/continuous-certification-program/>`_.
You can see the currently certified products in the `ONF marketplace <https://opennetworking.org/marketplace/?_product_project=voltha>`_.
-The following document describes the procedure to include and certify an OLT or an ONU with VOLTHA.
-The process of getting a product certified consists of several phases:
+The following document describes the procedure to include and certify an
+OLT or an ONU with VOLTHA. The process of getting a product certified
+consists of several phases:
- testing and validation with VOLTHA at the vendor premises
- showcase of successful integration with VOLTHA to the TST
-- shipment and integration of the product (OLT/ONU) at a community lab (e.g. Berlin with DT)
+- shipment and integration of the product (OLT/ONU) at a community lab
+ (e.g. Berlin with DT)
- Creation of automated CI jobs in Jenkins that start nightly automation tests.
-- Test maintenance. It's the Vendors and the VOLTHA community responsibility to maintain the created tests.
+- Test maintenance. It's the Vendors and the VOLTHA community responsibility
+ to maintain the created tests.
-Finally a brief Description of the device and a point of contact need to be sent to
-`Michelle Roth @ ONF <michelle@opennetworking.org>`_
-to be showcased in the `marketplace <https://opennetworking.org/marketplace/?_product_project=voltha>`_ after successful verification.
+Finally a brief Description of the device and a point of contact need to
+be sent to `Michelle Roth @ ONF <mroth@linuxfoundation.org>`_ to be
+showcased in the `marketplace <https://opennetworking.org/marketplace/?_product_project=voltha>`_ after successful verification.
-Once all these steps are completed the product will be certified for the next release of VOLTHA.
-Let's describe each phase in detail.
+Once all these steps are completed the product will be certified for
+the next release of VOLTHA. Let's describe each phase in detail.
Vendor's premises Testing
-------------------------
@@ -46,14 +49,16 @@
any one of the ONF community lab, including a wiring diagram (if needed) Currently there are two locations:
- DT Office in Berlin, Germany. Address: Winterfeldtstraße 21, 10781 Berlin, Germany. Point of contact `Bjoern Nagel @ DT <NagelB@telekom.de>`_
-- Radisys Laboratory in Hillsboro, Oregon
-Once the OLT arrives the technicians will rack it and wire it according to the diagram shared.
-For an OLT the NNI connection will be provided to the AGG switch and all the management will also be connected with
-management IP assigned according to the network of the pod.
-For an ONU it will be connected to one of the existing OLTs in the pod, according to space,
-technology and topology requirements.
-Once all the racking and wiring is complete the device will appear under the ONF network, accessible via VPN.
+Once the OLT arrives the technicians will rack it and wire it according to
+the diagram shared. For an OLT the NNI connection will be provided to the
+AGG switch and all the management will also be connected with management IP
+assigned according to the network of the pod.
+
+For an ONU it will be connected to one of the existing OLTs in the pod,
+according to space, technology and topology requirements. Once all the
+racking and wiring is complete the device will appear under the ONF network,
+accessible via VPN.
Automated CI Jobs
-----------------
@@ -74,12 +79,14 @@
and `kubernetes example <https://github.com/opencord/pod-configs/blob/master/kubernetes-configs/menlo-certification-pod-radisys-1600g.conf>`_
- voltha-system-tests. Adds the sadis configuration for the OLT and the ONU. `Sadis Example <https://github.com/opencord/voltha-system-tests/blob/master/tests/data/menlo-certification-pod-radisys-1600g-sadis-DT.json>`_
-Once these are created and merged the job will appear on jenkins and run accordingly.
+Once these are created and merged the job will appear on jenkins and
+run accordingly.
ONU
+++
-A new ONU it's attached to an existing OLT, so just the information for that ONU needs to be added to the proper
-OLT files.
+
+A new ONU it's attached to an existing OLT, so just the information for
+that ONU needs to be added to the proper OLT files.
The required patches are:
@@ -89,8 +96,9 @@
Job maintenance
---------------
-It's the responsibility of the Vendor, the VOLTHA TST and the community at large to mantain, manage and update the job
-to make sure the OLT gets certified for each of the following VOLTHA releases.
+It's the responsibility of the Vendor, the VOLTHA TST and the community at
+large to mantain, manage and update the job to make sure the OLT gets
+certified for each of the following VOLTHA releases.
@@ -98,5 +106,4 @@
------------
For any further information please contact:
-- `Timon Sloane <timon@opennetworking.org>`_
-- `Michelle Roth <michelle@opennetworking.org>`_
+- `Michelle Roth <mroth@opennetworking.org>`_