starlingx/specs
Code Issues Proposed changes

Merge "Standardize Flock Package Versioning"

Browse Source
This commit is contained in:
Zuul 2019-09-24 23:38:11 +00:00 committed by Gerrit Code Review
commit 4cafd9dd1f
1 changed files with 230 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

230
doc/source/specs/stx-3.0/approved/standardize_flock_versioning.rst Normal file
View File

@ -0,0 +1,230 @@
..
This work is licensed under a Creative Commons Attribution 3.0 Unported
License. http://creativecommons.org/licenses/by/3.0/legalcode
====================================
Standardize Flock Package Versioning
====================================
Problem description
===================
Currently all original StarlingX services and packages have a common base
version of 1.0 or 1.0.0 as defined in the rpm specfiles, before
TIS_PATCH_VER is applied. The build system creates tarballs and whl files
with the base version (without TIS_PATCH_VER) and the version is also
attached the generated RPM file (with TIS_PATCH_VER). While this version
is intended to be an API version, it is also being applied to packaging.
While the RPM package versions are unique based on the %{tis_patch_ver}
being part of the "Release" component of the RPM package name, this does
not fully reflect the actual version of the packages in the repo. The
proposed approach would initially version all packages in a repo with the
same PBR generated %{version} with the unique %{release} containing
tis_patch_ver value (or something similar).
A common versioning approach is highly beneficial across all of these
components. This supports the packaging and re-use of these components in
multiple Linux distributions and in containers.
Every packaging toolchain has its own build recipe requirements to create
packages. They usually require the ability to generate a proper version from
the source code or code repository. StarlingX leverages much of the tooling
used by OpenStack projects. Having a versioning scheme that deviates
significantly from those used by OpenStack creates additional work and
cognitive load for developers and consumers of these components.
Use Cases
=========
* Publishing packages to RPM repositories requires a predictable versioning
scheme. OS packaging expects a scheme approximating semantic versioning [0].
* Independent component versions allow interim code releases between the
integrated StarlingX releases in the future. This is most useful in library
and client components, such that they can be consumed by independently of the
integrated release.
Proposed change
===============
StarlingX will adopt the OpenStack Semantic Versioning [0] model based on the
usual MAJOR.MINOR.PATCH format where:
* MAJOR version increment indicates incompatible API changes or a new
integrated release
* MINOR version increment indicates new backward-compatible functionality or
dependency changes
* PATCH version increment indicates backward-compatible bug fixes
OpenStack's Python Build Reasonableness (PBR) [1] will be used to generate the
version by parsing semantically-versioned Git tags and walking the Git history
back to the last release tag. Each commit is denoted in the generated version
by an additional component based on the git commit-ish or an incrementing value
as described in the PBR documentation.
The Release string which contains the %{tis_patch_ver} will remain unchanged
and still appended to the final version string of the RPM.
For example, with a git tag of "2.0.0" in a repo and a TIS_PATCH_VER=7 for a
package in that repo, PBR will generate the version based on this tag and set
%{version} to 2.0.0, and the %{release} would be 7.tis. The final package
name would be <package>-2.0.0-7.tis.<arch>.rpm. Future version numbers would
be based on the number of commits from the 2.0.0 tag, so 5 commits later the
version string will be 2.0.1.dev5-7.tis (assuming TIS_PATCH_VER is unchanged).
Git repositories:
* Add Semantically-versioned Git tags to all flock package git repos.
* Packages in a single repo have the same version.
* Versioning is managed per repo, for example one repo could be at 2.0.1
and another at 2.0.4 if there has been more change to the second repo.
* This process, independent of policy, supports both keeping the major
versions synced with the integrated release or allowing them to diverge.
Build scripts and RPM spec files need to be improved:
* Build scripts need to be improved to use PBR to generate a proper version
from the Semantically-versioned Git tags.
* Build scripts will use rpmbuild tool to define "pkg_version" for SRPM build.
The spec file should be improved to accept it from build scripts.
* Build scripts will continue to use TIS_PATCH_VER as defined in
build_srpm.data.
Alternatives
------------
Manage the package version manually. Most version will remain at 1.0 along
with the TIS_PATCH_VERSION info.
Data model impact
-----------------
None
REST API impact
---------------
REST APIs is versioned separately as is done in many OpenStack projects to
allow them to evolve and be detectable by API consumers.
Security impact
---------------
None
Other end user impact
---------------------
None
Performance Impact
------------------
None
Other deployer impact
---------------------
None
Developer impact
----------------
To add new packages, it needs to update the spec file to accept "pkg_version"
definition from build scripts.
Releases (any version change) is handled by the release tooling. It does not
need developer practice.
Upgrade impact
--------------
None
This change only applies to flock packages (e.g. stx-fault).
TIS_PATCH_VERSION is removed from the package version. It should be handled
similar to existing upstream packages, e.g. from CentOS, that are unmodified
and have no TIS_PATCH_VERSION.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
Bin Yang (byangintel)
Other contributors:
Saul Wold (sgw-starlingx)
Repos Impacted
--------------
* All repos will be tagged
except docs, elections, governance, and specs
* Repos that generate artifact such as:
* starlingx/ansible-playbooks
* starlingx/clients
* starlingx/config
* starlingx/fault
* starlingx/gui
* starlingx/ha
* starlingx/metal
* starlingx/nfv
* starlingx/update
Work Items
----------
* Add setup.py and setup.cfg in non-pythonic repo for PBR to generate version.
* Improve the build scripts to generate package version with PBR.
* Improve the RPM spec file to accept the version from build scripts.
* Add git tag for version generation.
Dependencies
============
None
Testing
=======
This change should be transparent for the common developer, so no changes
should be noticed after this implementation. The proposed testing is:
* To have a full clean build: The build procedure shall be transparent for the
developer.
* Check the impacted packages' version manually.
* Validate installation is completed correctly and initial boot deployment
works
Documentation Impact
====================
Add a documentation to explain the version generation.
References
==========
[0] https://docs.openstack.org/pbr/latest/user/semver.html
[1] https://docs.openstack.org/pbr/latest/
History
=======