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/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.