VOL-4840 - Tracking ticket for release documentation.
conf.py
-------
o Define more external link macros to shorten URLs.
Misc
----
o Updated comments on version strings and misc items.
Change-Id: Ib4bc650e575bdc4b5c6a666c4147c8b93a41e797
diff --git a/VERSION b/VERSION
index 6eb05b9..c62007a 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.11.0-dev6
+2.11.0-dev7
diff --git a/conf.py b/conf.py
index 78b1d20..4a68580 100644
--- a/conf.py
+++ b/conf.py
@@ -12,8 +12,19 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
+##-------------------##
+##---] IMPORTS [---##
+##-------------------##
import os
+import sys
+from pathlib import Path
+if True:
+ pwd = Path(__file__).parent.as_posix()
+ sys.path.append(pwd)
+
+# -----------------------------------------------------------------------
+# -----------------------------------------------------------------------
def get_version():
with open("VERSION") as f:
return f.read().strip()
@@ -21,7 +32,7 @@
# -- Project information -----------------------------------------------------
project = u'VOLTHA Docs'
-copyright = u'2019-2022, VOLTHA Contributors & Open Networking Foundation'
+copyright = u'Copyright 2019-2023 Open Networking Foundation (ONF) and the ONF Contributors'
author = u'VOLTHA Contributors'
# The short X.Y version
@@ -270,9 +281,12 @@
# -- Options for extlinks extension ------------------------------------------
# ..seealso: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
# 'vhc' : 'https://gerrit.opencord.org/plugins/gitiles/voltha-helm-charts',
+
extlinks=\
{
'vol-jira' : ('https://jira.opencord.org/projects/VOL/issues/%s', 'jira::%s'),
+ # macros for gerrit or github URL construction
+ 'repo' : ('https://github.com/opencord/%s', 'repo::%s'),
'vol-ger' : ('https://gerrit.opencord.org/plugins/gitiles/%s', 'gerrit::%s'),
'vol-git' : ('https://github.com/opencord/%s', 'git::%s'),
}
diff --git a/howto/accounts.rst b/howto/accounts.rst
new file mode 100644
index 0000000..fba75ba
--- /dev/null
+++ b/howto/accounts.rst
@@ -0,0 +1,84 @@
+.. _my-reference-label:
+.. _gerrit-user-account:
+
+Getting Started
+###############
+
+- Register with ONF
+- gerrit user account
+- github user account
+
+Register with ONF
+=================
+
+Begin by registering with OpenNetworkingFoundation, this will create a
+user account for you to access resources: gerrit, jenkins, wiki, etc.
+
+- https://opennetworking.org/register/
+
+
+Gerrit user account
+===================
+
+Next navigate to gerrit.opencord.org, login and configure your user account
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- `Gerrit Login <https://gerrit.opencord.org/login/%2Fq%2Fstatus%3Aopen%2B-is%3Awip>`_
+
+- `User Settings <https://gerrit.opencord.org/settings/>`_
+ - Verify full name and display name fields are populated.
+ - Verify your email address is correct.
+
+- Generate and deploy an ssh key to interact with the repository:
+ - `Public SSH key <https://gerrit.opencord.org/settings>`_ (#SSHKeys)
+
+- Verify your ssh access
+
+.. sourcecode:: shell
+
+ # Generate a new ssh key
+ $ cd .ssh
+ $ ssh-keygen -t ed25519 -f id_gerrit -C 'tux@opennetworking.org'
+
+ # Connect passing -T, -p(ort), -i(dentity)
+ $ ssh -T -p 29419 -i ~/.ssh/id_gerrit 'tux@opennetworking.org@gerrit.opencord.org'
+
+ $ ssh-add ~/.ssh/id_gerrit
+ $ ssh -T -p 29419 'tux@opennetworking.org@gerrit.opencord.org'
+
+
+
+Github user account
+===================
+
+Enable two-factor authentication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- https://github.com/settings/security
+
+Generate and upload a public ssh key to interact with the repository:
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+- https://github.com/settings/keys
+
+
+
+Git config settings
+===================
+
+.. sourcecode:: shell
+
+ ## Config required by git:
+ $ git config --global user.name 'Tux Penguin'
+ $ git config --global user.email 'tux@opennetworking.org'
+
+ ## Config required by gerrit:
+ $ git config --global gitreview.username 'tux@opennetworking.org'
+
+ ## Convenience:
+ $ git config --global alias.br branch
+ $ git config --global alias.ci commit
+ $ git config --global alias.co checkout
+ $ git config --global alias.st status
+
+ ## Optional configs:
+ $ git config --global color.ui auto
+ $ git config --global pater.diff false
diff --git a/howto/development.rst b/howto/development.rst
new file mode 100644
index 0000000..fd65a8e
--- /dev/null
+++ b/howto/development.rst
@@ -0,0 +1,26 @@
+Development
+###########
+
+- `Gerrit Login <https://gerrit.opencord.org/login/%2Fq%2Fstatus%3Aopen%2B-is%3Awip>`_
+
+Locate a VOLTHA :ref:`SSH Key <gerrit-user-account>` of interest
+================================================================
+
+- Clone repository `repo:voltha-docs <https://gerrit.opencord.org/plugins/gitiles/voltha-docs>`_
+
+.. sourcecode:: shell
+
+ $ mkdir -p ~/sandbox
+ $ cd ~/sandbox
+ $ git clone ssh://gerrit.opencord.org:29418/voltha-docs
+ $ cd voltha-docs
+
+- TODO
+ - HOWTO: edit branch=main or create branch=dev-user
+ - HOWTO: Commit changes
+ - HOWTO: gerrit review
+ - HOWTO: jenkins - check job status from review screen history.
+ - HOWTO: gerrit review screen, react to feedback, augment patch.
+ - HOWTO: commit --amend
+ - HOWTO: request merge
+ - HOWTO: include reference to `System Test Development <https://wiki.onosproject.org/display/ONOS/Gerrit+Workflow+for+System+Test+Development>`
diff --git a/howto/doc_fixes b/howto/doc_fixes
index 9fd733d..98e439b 100644
--- a/howto/doc_fixes
+++ b/howto/doc_fixes
@@ -1,2 +1,3 @@
D000 Duplicate explicit target name
- - Suffix ` <>`_ URLs with a double underscore
\ No newline at end of file
+ - Suffix ` <>`_ URLs with a double underscore
+
diff --git a/howto/index.rst b/howto/index.rst
index 1f23a6c..79f21af 100644
--- a/howto/index.rst
+++ b/howto/index.rst
@@ -7,4 +7,5 @@
code/index
edit_voltha_docs
release/index
+ ssh_access
voltha_repositories
diff --git a/howto/release/components/index.rst b/howto/release/components/index.rst
index f13b276..b859afe 100644
--- a/howto/release/components/index.rst
+++ b/howto/release/components/index.rst
@@ -64,6 +64,7 @@
.. toctree::
onos_dependencies
+ voltha-protos
voltctl/index
voltctl/install
diff --git a/howto/release/components/onos_dependencies.rst b/howto/release/components/onos_dependencies.rst
index 2d0d8c8..5068cd3 100644
--- a/howto/release/components/onos_dependencies.rst
+++ b/howto/release/components/onos_dependencies.rst
@@ -151,3 +151,12 @@
.. code:: XML
<sadis.api.version>5.10.0</sadis.api.version>
+
+maclearner
+^^^^^^^^^^
+
+pppoeagent
+^^^^^^^^^^
+
+segmentrouting
+^^^^^^^^^^^^^^
diff --git a/howto/release/components/voltha-lib-go.rst b/howto/release/components/voltha-lib-go.rst
new file mode 100644
index 0000000..da1b057
--- /dev/null
+++ b/howto/release/components/voltha-lib-go.rst
@@ -0,0 +1,25 @@
+VOLTHA Components: voltha-protos
+================================
+
+Dependencies
+------------
+
+- update go.mod
+
+ - voltha-protos
+
+
+Validate
+--------
+
+Versioning
+----------
+
+- Based on VERSION file contents in root directory of the repository.
+
+Release
+-------
+
+- Bump VERSION file to a non-dev semantic version.
+- See Validate above
+- Commit and approve to trigger a build
diff --git a/howto/release/components/voltha-protos.rst b/howto/release/components/voltha-protos.rst
new file mode 100644
index 0000000..9de5270
--- /dev/null
+++ b/howto/release/components/voltha-protos.rst
@@ -0,0 +1,25 @@
+VOLTHA Components: voltha-protos
+================================
+
+Dependencies
+------------
+
+- google-api library version
+
+Validate
+--------
+
+- make lint
+- make test
+
+Versioning
+----------
+
+- Based on VERSION file contents in root directory of the repository.
+
+Release
+-------
+
+- Bump VERSION file to a non-dev semantic version.
+- See Validate above
+- Commit and approve to trigger a build
diff --git a/howto/release/hierarchy/index.rst b/howto/release/hierarchy/index.rst
new file mode 100644
index 0000000..f901eac
--- /dev/null
+++ b/howto/release/hierarchy/index.rst
@@ -0,0 +1,43 @@
+VOLTHA Components
+=================
+
+voltha-onos
+^^^^^^^^^^^
+
+- `dependencies.xml <https://github.com/opencord/voltha-onos/blob/master/dependencies.xml>`_
+
+Dependencies.xml is the last step of the release of ONOS + APPS, it's in
+the voltha-onos repo and it's the last element you need to update so that
+the voltha-onos docker image can be built with all the released apps on top
+of the selected ONOS image.
+
+Use dependencies.xml to populate the release notes version grid for ONOS.
+
+ofagent-go
+^^^^^^^^^^
+- `deps: go.mod <https://gerrit.opencord.org/plugins/gitiles/ofagent-go/+/refs/heads/master/go.mod>`_
+
+ - voltha-lib-go
+ - voltha-protos
+
+Relase: voltctl
+
+ - update: repo:ci-management:vars/installVoltctl.groovy
+
+voltha-protos
+^^^^^^^^^^^^^
+- `deps: go.mod <https://gerrit.opencord.org/plugins/gitiles/ofagent-go/+/refs/heads/master/go.mod>`_
+
+ - voltha-lib-go
+ - voltha-protos
+
+Relase: voltctl
+
+ - update: repo:ci-management:vars/installVoltctl.groovy
+
+See Also
+========
+- `VOLTHA Release Process <https://docs.voltha.org/master/overview/release_process.html?highlight=charts%20yaml>`_
+- `release_notes: Release Process <https://docs.voltha.org/master/release_notes/release_process.html>`_
+- `VOLTHA and ONOS Software Update Procedure <https://docs.voltha.org/master/operations/software-upgrade.html?highlight=set%20global%20image>`_
+- `Helm Chart Deployment <https://docs.voltha.org/master/voltha-helm-charts/README.html?highlight=voltctl>`_
diff --git a/howto/release/index.rst b/howto/release/index.rst
index da347a5..db164b3 100644
--- a/howto/release/index.rst
+++ b/howto/release/index.rst
@@ -4,6 +4,7 @@
:maxdepth: 2
components/index
+ hierarchy/index
voltctl/index
voltctl/install
diff --git a/howto/ssh_access.rst b/howto/ssh_access.rst
new file mode 100644
index 0000000..d7d9120
--- /dev/null
+++ b/howto/ssh_access.rst
@@ -0,0 +1,80 @@
+Gerrit SSH Access
+#################
+
+- `Gerrit Login <https://gerrit.opencord.org/login/%2Fq%2Fstatus%3Aopen%2B-is%3Awip>`_
+
+Generate an :ref:`SSH Key <gerrit-user-account>` for access
+============================================================
+
+.. sourcecode:: shell
+
+ $ ssh-keygen -t ed25519 -f id_gerrit -C 'tux@opennetworking.org'
+
+- Login and configure gerrit
+
+- Verify your ssh connection (manual/explicit args)
+ - ssh -T -p 29419 -i ~/.ssh/id_gerrit tux@gerrit.opencord.org
+ - -T # disable pseudo terminal access, simple verify
+ - -p(port)
+ - -i(dentity) # ssh key
+ - Expect to see::
+ \*\*\*\* Welcome to Gerrit Code Review \*\*\*\*
+
+ Hi tux, you have successfully connected over SSH.
+
+ Unfortunately, interactive shells are disabled.
+
+
+Load your ssh key(s) to prompt for a passprase once
+===================================================
+
+.. sourcecode:: shell
+
+ # ssh-add will prompt for the passphrase for your key.
+ # This is a one-time operation per login session.
+ $ ssh-add ~/.ssh/id_gerrit
+ $ ssh-add -l
+
+Create ~/.ssh/config to simplify your connections
+=================================================
+.. sourcecode:: shell
+
+ FILE: ~/.ssh/config
+ # IdentitiesOnly yes only use identity provided, no fallback
+
+ Host github.com
+ IdentityFile ~/.ssh/github.com/id_ed25519
+ IdentitiesOnly yes
+ # (default) Port 22
+ User tux
+
+ Host gerrit.opencord.org
+ Hostname gerrit.opencord.org
+ IdentityFile ~/.ssh/gerrit.opencord.org/id_ed25519
+ IdentitiesOnly yes
+ Port 29418
+ User tux@opennetworking.org
+
+With ~/.ssh/config setup simply connect to the target machine:
+==============================================================
+ - ssh gerrit.opencord.org
+
+
+Secure permissions on ~/.ssh
+============================
+
+.. sourcecode:: shell
+
+ $ chown -R {my_login}:{my_login} ~/.ssh
+ $ chmod -R ~/.ssh u+rwx,og-rwx
+ $ find ~/.ssh -type d -print0 | xargs -0 chmod u=rwx
+ $ find ~/.ssh -type f -print0 | xargs -0 chmod u=r
+ $ find ~/.ssh -name '*.pub' -type f -print0 | xargs -0 chmod u=rw
+ $ chmod u=rw ~/.ssh/config ~/.ssh/known_hosts* ~/.ssh/authorized_keys
+
+Debugging connection problems
+===============================
+ - ssh [-v | -vv | -vvv ] to enable connection debugging.
+ - For conneciton problems be explicit when specifying arguments:
+ - ssh -p(ort) -i(dentity) {user}@{host}
+ - Use ssh-add -D to clear your keyring and force passphrase prompting.
diff --git a/makefiles/virtualenv.mk b/makefiles/virtualenv.mk
index faa7c60..e8cab77 100644
--- a/makefiles/virtualenv.mk
+++ b/makefiles/virtualenv.mk
@@ -20,13 +20,13 @@
vst_venv-2 : vst_venv/bin/activate requirements.txt
-vst_venv/bin/activate:
- virtualenv -p python3 $@ ;\
- source ./$@/bin/activate ;\
- python -m pip install -r requirements.txt
+vst_venv/bin/activate: requirements.txt
+ virtualenv -p python3 $@
-zzz: xyz
-xyz: vst_venv/bin/activate
- source vst_venv/bin/activate
+ @echo
+ @[ -r requirements.txt ]\
+ && { echo "python -m pip install -r requirements.txt"; }\
+ && source ./$@/bin/activate\
+ && python -m pip install -r requirements.txt
# [EOF]
diff --git a/overview/release_process.rst b/overview/release_process.rst
index 37b84cb..ef88956 100644
--- a/overview/release_process.rst
+++ b/overview/release_process.rst
@@ -83,16 +83,32 @@
1. Build with parameters: use the name of the repo (not of the app itself)
2. Wait for build to complete
3. Merge the patches on gerrit https://gerrit.opencord.org/q/owner:do-not-reply%2540opennetworking.org
-4. It will trigger a publish job (https://jenkins.opencord.org/job/maven-publish_sadis/) that publish the artifact in
- the staging repo on `sonatype <https://oss.sonatype.org>`_, you need to release it:
- * Login on sonatype (for username and password contact michelle@opennetworking.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)
- * In the top right search for last part of the app name (eg: olt)
- * Click release (top left bar, small button)
-5. Wait until the artifacts are published https://search.maven.org/search?q=g:org.opencord
-6. Go in other apps, update the dependency of released from x.y.z-SNAPSHOT to x.y.z
+
+ - Two pull requests are created modifying pom.xml.
+ - Approve patch one (-SNAPSHOT: no) to initiate a release build.
+ - Approve patch two (-SNAPSHOT: yes) to revert pom.xml to a non-release version.
+
+4. Approval and merge will trigger a `jenkins job <https://jenkins.opencord.org/job/maven-publish_sadis/>`_ that publish
+ an artifact into the staging repo on `sonatype <https://oss.sonatype.org>`_. From there the artifact will need
+ to be released into maven central.
+
+ - Login on sonatype (for username and password contact michelle@opennetworking.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)
+ - In the top right search for last part of the app name (eg: olt)
+ - Click release (top left bar, small button)
+
+5. Wait until the artifacts are published
+
+ - https://search.maven.org/search?q=g:org.opencord
+ - https://search.maven.org/artifact/org.opencord/dhcpl2relay/2.9.0/pom
+
+6. Iterate through apps:
+
+ - Modify pom.xml and dependencies.xml
+ - Update version string for all released dependencies.
+
7. Start over with new app
.. note::
@@ -217,3 +233,10 @@
- Then push a commit changing to `.1-SNAPSHOT` more (see e.g. https://gerrit.opencord.org/c/igmpproxy/+/19589)
- Then push you changes (e.g. https://gerrit.opencord.org/c/igmpproxy/+/19590)
- Then release as per the process above.
+
+See Also
+========
+- `VOLTHA Release Process <https://docs.voltha.org/master/overview/release_process.html?highlight=charts%20yaml>`_
+- `release_notes: Release Process <https://docs.voltha.org/master/release_notes/release_process.html>`_
+- `VOLTHA and ONOS Software Update Procedure <https://docs.voltha.org/master/operations/software-upgrade.html?highlight=set%20global%20image>`_
+- `Helm Chart Deployment <https://docs.voltha.org/master/voltha-helm-charts/README.html?highlight=voltctl>`_
diff --git a/release_notes/voltha_2.11.rst b/release_notes/voltha_2.11.rst
index 0e7174c..a8f2d62 100644
--- a/release_notes/voltha_2.11.rst
+++ b/release_notes/voltha_2.11.rst
@@ -194,10 +194,10 @@
- `X <https://github.com/opencord/igmpproxy/tree/2.7.0>`__
* - `kafka <https://gerrit.opencord.org/gitweb?p=kafka-onos.git;a=summary>`_
-
- - ``2.9.0``
+ - ``2.11.1``
-
- -
- -
+ - `X <https://gerrit.opencord.org/plugins/gitiles/kafka-onos/+/refs/tags/2.11.1>`__
+ - `X <https://github.com/opencord/kafka-onos/tree/2.11.1>`__
* - `mcast <https://gerrit.opencord.org/gitweb?p=mcast.git;a=summary>`_
-
- ``2.8.0``
@@ -218,22 +218,22 @@
- `X <https://github.com/opencord/sadis/tree/5.10.0>`__
* - `bng <https://gerrit.opencord.org/gitweb?p=bng.git;a=summary>`_
-
- - ``2.2.0``
+ - ``2.4.0``
-
- -
- -
+ - `X <https://github.com/opencord/bng/tree/2.4.0>`__
+ - `X <https://gerrit.opencord.org/plugins/gitiles/bng/+/refs/tags/2.4.0>`__
* - `pppoeagent <https://gerrit.opencord.org/plugins/gitiles/pppoeagent/>`_
-
- ``1.2.0``
-
- -
- -
+ - `X <https://gerrit.opencord.org/plugins/gitiles/pppoeagent/+/refs/tags/1.2.1>`__
+ - `X <https://github.com/opencord/pppoeagent/tree/1.2.1>`__
* - `olttopology <https://gerrit.opencord.org/plugins/gitiles/olttopology/>`_
-
- - ``1.2.0``
+ - ``1.2.0`` ``latest: 1.2.1``
-
- -
- -
+ - `X <https://gerrit.opencord.org/plugins/gitiles/olttopology/+/refs/tags/1.2.1>`__
+ - `X <https://github.com/opencord/olttopology/tree/1.2.1>`__
VOLTHA Components
+++++++++++++++++
@@ -327,17 +327,35 @@
- `X <https://gerrit.opencord.org/plugins/gitiles/voltha-openolt-adapter/+/refs/tags/v4.2.10>`__
- `X <https://github.com/opencord/voltha-openolt-adapter/tree/v4.2.11>`__
* - `voltha-protos <https://github.com/opencord/voltha-protos/releases/tag/v5.2.5>`__
- - ``master: 5.3.6``
- - ``5.3.6``
+ - ``5.3.7``
+ - ``5.3.7``
-
- - `X <https://gerrit.opencord.org/plugins/gitiles/voltha-protos/+/refs/tags/v5.3.6>`__
- - `X <https://github.com/opencord/voltha-protos/tree/v5.3.6>`__
+ - `X <https://gerrit.opencord.org/plugins/gitiles/voltha-protos/+/refs/tags/v5.3.7>`__
+ - `X <https://github.com/opencord/voltha-protos/tree/v5.3.7>`__
* - `voltha-system-tests <https://github.com/opencord/voltha-system-tests/releases/tag/2.9.0>`__
- ``2.11.10``
-
-
- `X <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/tags/2.11.10>`__
- `X <https://github.com/opencord/voltha-system-tests/tree/2.11.10>`__
+ * - maclearner
+ - ``1.2.1``
+ -
+ -
+ -
+ -
+ * - ppoeagent
+ - ``1.2.1``
+ -
+ -
+ -
+ -
+ * - segmentrouting
+ - ``3.0.0``
+ -
+ -
+ -
+ -
Helm Chart Versions
diff --git a/testing/index.rst b/testing/index.rst
index 2124721..99771ec 100644
--- a/testing/index.rst
+++ b/testing/index.rst
@@ -2,14 +2,18 @@
===========================
Below are links to the documentation generated by ``robot.libdoc`` from the
-Robot resources in the voltha-system-tests repository.
+Robot resources in :repo:`voltha-system-tests`.
-| These files can also be generated locally by checking out the repo and running:
+| These files can also be generated locally by checking out the repo and running one of:
-- % **make gendocs**
+.. code:: bash
- - `voltha-system-tests (gerrit) <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests>`_
- - `voltha-system-tests (github) <https://github.com/opencord/voltha-system-tests>`_
+ | % **make gendocs**
+ | % **make html**
+ | % **make reload**
+
+ - :repo:`voltha-system-tests` (gerrit)
+ - :repo:`voltha-system-tests` (github)
Libraries
---------