Document updating repo:voltha-protos
VERSION
-------
o Bump version string for the build.
o https://docs.voltha.org/master/overview/contributing.html?highlight=version#versioning
howto/code/index.rst
howto/code/voltha-protos.rst
----------------------------
o Begin documenting howto edit volha-protos, commands and dependencies.
o 'go.mod' urls in the grid are suffixed by a double-underscore to
notify sphinx/rst document checking that name duplication is OK.
Change-Id: I0abff8c925fa86943c16c9eae8b181b8f0479bd3
diff --git a/VERSION b/VERSION
index 8d81fbf..ae93586 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.12.6-dev3
+2.12.7
diff --git a/howto/code/index.rst b/howto/code/index.rst
index 998109c..3041736 100644
--- a/howto/code/index.rst
+++ b/howto/code/index.rst
@@ -8,3 +8,4 @@
job-failures
linting
pull_request
+ voltha-protos
diff --git a/howto/code/voltha-protos.rst b/howto/code/voltha-protos.rst
new file mode 100644
index 0000000..2403b63
--- /dev/null
+++ b/howto/code/voltha-protos.rst
@@ -0,0 +1,96 @@
+Modifying repository voltha-protos
+==================================
+
+#. Clone repository `voltha-protos <https://gerrit.opencord.org/plugins/gitiles/voltha-protos/+/refs/heads/master>`_
+#. Modify structures, sources & makefiles as needed.
+#. Build, test and lint locally to validate sources.
+#. Commit changes, code review, jenins build and deploy.
+#. Update external dependent repositories to use the new version.
+
+Clone, edit, build & test
+-------------------------
+
+.. code:: bash
+
+ git clone ssh://gerrit.opencord.org:29418/voltha-protos.git
+ cd voltha-protos
+ vi ...
+
+ make build
+ make test
+ make lint
+
+.. list-table:: Build & Test locally
+ :widths: 30, 80
+ :header-rows: 1
+
+ * - Command
+ - Description
+ * - make sterile
+ - Remove previously generated targets
+ * - make protos
+ - Generate prototypes for go, java & python (dependency for target:build)
+ * - make build
+ - make protos; compile: go, java & python
+ * - make test
+ - Validate proto changes
+ * - make lint
+ - Syntax check sources prior to commit.
+
+Update all external repositories to consume the new repo:voltha-protos version
+------------------------------------------------------------------------------
+
+- Each external VOLTHA repository will need to have dependencies mentioned in
+ the file go.mod updated.
+- Rebuild each repository in hierarchial order also updating external libs as
+ they are rebuilt.
+
+.. list-table:: External repositories to modify
+ :widths: 30, 80
+ :header-rows: 1
+
+ * - Repository
+ - File(s) to edit
+ * - bbsim
+ - `go.mod <https://gerrit.opencord.org/plugins/gitiles/bbsim/+/refs/heads/master/go.mod>`_
+ * - ofagent-go
+ - `go.mod <https://gerrit.opencord.org/plugins/gitiles/ofagent-go/+/refs/heads/master/go.mod>`__
+ * - voltctl
+ - `go.mod <https://gerrit.opencord.org/plugins/gitiles/voltctl/+/refs/heads/master/go.mod>`__
+ * - voltha-go
+ - `go.mod <https://gerrit.opencord.org/plugins/gitiles/voltha-go/+/refs/heads/master/go.mod>`__
+ * - voltha-go-controller
+ - `go.mod <https://gerrit.opencord.org/plugins/gitiles/voltha-go-controller/+/refs/heads/master/go.mod>`__
+ * - voltha-lib-go
+ - `go.mod <https://gerrit.opencord.org/plugins/gitiles/voltha-lib-go/+/refs/heads/master/go.mod>`__
+ * - voltha-openolt-adapter
+ - `go.mod <https://gerrit.opencord.org/plugins/gitiles/voltha-openolt-adapter/+/refs/heads/master/go.mod>`__
+ * - voltha-openonu-adapter-go
+ - `go.mod <https://gerrit.opencord.org/plugins/gitiles/voltha-openonu-adapter-go/+/refs/heads/master/go.mod>`__
+ * - voltha-system-tests
+ - `requirements.txt <https://gerrit.opencord.org/plugins/gitiles/voltha-system-tests/+/refs/heads/master/requirements.txt>`_ (virtualenv/testing)
+
+.. list-table:: Foreach external repository
+ :widths: 30, 80
+ :header-rows: 1
+
+ * - Command
+ - Description
+ * - vi {repo}/go.mod
+ - Bump version of repo:voltha-proto to latest published
+ * - vi {repo}/go.mod
+ - Bump external module version(s) during hierarcical build.
+ * - go mod edit -replace [...]
+ - Use the go mod tool to update version of voltha-protos and friends.
+ * - go mod tidy
+ - Cleanup syntax issues in golang source that will fail your pending commit
+ * - go mod vendor
+ - | Update sources and dependencies beneath the vendor/ directory.
+ | See also `go-mod-vendor <https://go.dev/ref/mod#go-mod-vendor>`_, `Packages & Modules <https://golangbyexample.com/packages-modules-go-second/>`_
+ * - make build
+ - Compile with updated module dependencies.
+ * - make test
+ - Sanity check everything is still working.
+ * - make lint LOCAL_FIX_PERMS=1
+ - | Syntax check sources for problems prior to checkin.
+ | LOCAL_FIX_PERMS=1 (optional) can workaround docker related permission problems.