blob: 09c8c2656df262b50e5984a5afe953f63e2ff9b8 [file] [log] [blame]
Joey Armstrongb0b790b2022-12-14 20:35:54 -05001VOLTHA Release: voltctl
2=======================
3
Joey Armstrong7c422562024-04-01 16:35:46 -04004Source
5------
6
7.. list-table:: Release resources
8 :widths: 10, 60
9 :header-rows: 1
10
11 * - Source
12 - Description
13 * - `VERSION file <https://gerrit.opencord.org/plugins/gitiles/voltctl/+/refs/heads/master/VERSION>`__
14 - Contains the tool version to build and/or release.
15 * - `jjb/shell/github-release.sh <https://gerrit.opencord.org/plugins/gitiles/ci-management/+/refs/heads/master/jjb/shell/github-release.sh>`__
16 - Shell script used to publish release candidates to github.
17
18Development
19-----------
20
21.. code-block:: shell-session
22 :caption: Build and test volctl locally
23
24 % git clone ssh://gerrit.opencord.org:29418/voltctl.git
25 % cd voltctl
26
27 % make help
28 % make lint # [optional] lint-sanity lint-style lint-mod sca
29 % make build
30 % make check # [optional] test
31
32 % make release # compile release binaries
33 % make install
34
35
Joey Armstrongb0b790b2022-12-14 20:35:54 -050036Release Builds howto:
37---------------------
Joey Armstrong7c422562024-04-01 16:35:46 -040038
39- Increment the `VERSION file <https://gerrit.opencord.org/plugins/gitiles/voltctl/+/refs/heads/master/VERSION>`__ to a major or minor point release.
40
41.. list-table:: VERSION file, Symantec version strings
42 :widths: 10, 10, 60
43 :header-rows: 1
44
45 * - Version
46 - Artifact
47 - Description
48 * - 1.2.3
49 - docker
50 - Publish artifacts
51 * - 1.2.3-dev
52 -
53 - Dev patch, build and test w/o external publishing.
54
55- Merging the patch will initiate a jenkins job to build components
Joey Armstrongb0b790b2022-12-14 20:35:54 -050056
Joey Armstrong8d62cd92022-12-22 13:53:48 -050057 - `repo::voltctl <https://gerrit.opencord.org/plugins/gitiles/voltctl/+/refs/heads/master>`__, Gerrit example: `33551 <https://gerrit.opencord.org/c/voltctl/+/33551>`_.
58 - At least two jenkins jobs need to run:
59
Joey Armstrong7c422562024-04-01 16:35:46 -040060 - `version-tag_wildcard <https://jenkins.opencord.org/job/version-tag_wildcard/>`__
61
62 - Verify VERSION file string is sane.
63
64 - `github-release_voltctl <https://jenkins.opencord.org/job/github-release_voltctl/>`__
65
66 - Publish tool to github.
67
Joey Armstrong8d62cd92022-12-22 13:53:48 -050068
69- Verify `git tags <https://github.com/opencord/voltctl/tags>`_
70
71 - A SemVer tag was created (vee prefix v{semver} signifies a golang package).
Joey Armstrong7c422562024-04-01 16:35:46 -040072 - Verify the latest `package(v1.8.45) <https://github.com/opencord/voltctl/releases>`_ contains more than just source archives (gz, zip):
Joey Armstrong8d62cd92022-12-22 13:53:48 -050073 - The `tags page <https://github.com/opencord/voltctl/tags>`_ index lacks ``Notes`` and ``Downloads`` links.
74
Joey Armstrongae15c262023-03-29 15:36:28 -040075 - A valid package(v1.7.6) _ will include:
Joey Armstrong8d62cd92022-12-22 13:53:48 -050076
77 - The `tags page <https://github.com/opencord/voltctl/tags>`_ index contains ``Notes`` and ``Downloads`` links.
78 - A checksum file
Joey Armstrong7c422562024-04-01 16:35:46 -040079 - Versioned voltctl binaries for several platforms (darwin, linux, windows)
Joey Armstrong8d62cd92022-12-22 13:53:48 -050080 - Source code bundles (tar.gz and zip).
81
82- `Released version <https://api.github.com/repos/opencord/voltctl/releases/latest>`_ will be consumed by jenkins installer vars/installVoltctl.groovy.
83
Joey Armstrongb0b790b2022-12-14 20:35:54 -050084
85Create an official voltctl release
86----------------------------------
87- `installVoltctl.groovy <https://gerrit.opencord.org/plugins/gitiles/ci-management/+/refs/heads/master/vars/installVoltctl.groovy#53>`_
Joey Armstrong8d62cd92022-12-22 13:53:48 -050088 depends on `github/releases/latest <https://api.github.com/repos/opencord/voltctl/releases/latest>`_ for versioned release information.
Joey Armstrongb0b790b2022-12-14 20:35:54 -050089
Joey Armstrong8d62cd92022-12-22 13:53:48 -050090- To generate a release commit changes to `repo::voltctl <https://gerrit.opencord.org/plugins/gitiles/voltctl>`__:
Joey Armstrongb0b790b2022-12-14 20:35:54 -050091
Joey Armstrong8d62cd92022-12-22 13:53:48 -050092 - Modify VERSION file major/minor numbers for the upcoming release.
93 - Remove any -dev or patch modifiers.
94 - Create a pull request for review.
95 - Changes will be published when the jenkins job github-release-voltctl is run.
Joey Armstrongb0b790b2022-12-14 20:35:54 -050096
97- Verify the release version contains a checksum file:
98
99 - checksum.SHA256
100 - voltctl-1.7.6-darwin-amd64
101 - voltctl-1.7.6-linux-amd64
102 - voltctl-1.7.6-linux-arm64
103 - voltctl-1.7.6-windows-amd64
104 - Source code (zip)
105 - Source code (tar.gz)
106
Joey Armstrong7c422562024-04-01 16:35:46 -0400107Manual release
108--------------
109
110Avoid this answer whenever possible but when peripheral breakage or volume
111prevents publishing a new version of voltctl, a the tool can be published
112manually. The user will need repository publishing permissions on github
113and creation of a github api key for their account.
114
115Under the hood the `github gh command <https://cli.github.com/>`__ will handle all the heavy lifting.
116
117TODO
118^^^^
119
120- Document key creation.
121- Document github-release.sh command line and use.
122
Joey Armstrongb0b790b2022-12-14 20:35:54 -0500123:ref:`voltctl-see-also`