[Starlingx-discuss] Flock Versioning for packaging
StarlingX Community:
Currently the versioning of the flock is mostly matching their internal API '1.0-<tis_patch_ver>.tis'. This is historical since the Upgrade process is a complete re-image of the disk from ISO and doesn't actually have to increase the version number between releases (other than maybe the tis_patch_ver).
Moving forward we need to consider using the OpenStack Semantic Versioning [0], and looking at PBR (Python Build Reasonableness) [1] to generate the version that is based on MAJOR.MINOR.PATCH where:
- MAJOR version when you make incompatible API changes - MINOR version when you add functionality in a backwards-compatible manner - PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
We understand the requirement that the Flock has across releases to preserve backward compatibility, likely the MAJOR will never change, but we should be considering that we bump the MINOR on each release and reset PATCH and bump PATCH based on doing a CVE, or required bug fix between releases.
To enable PBR, we would need to change the Python related setup to use setup.cfg with pbr, some of this work has started by Dean with Devstack related work. PBR won't address all packages since some are non-Python. We would also have to add versoining tags into git for PBR to work correctly. PBR can also help generate information for packaging.
During development, X.Y.Z.dev<N> or a "+g<hash>" is possible for builds. This is needed to during the development phase in order to track changes and help debug failures based on what packages are installed, it could also allow for independently updating of packages on a target system using standard packaging tools. This will be particularly important if we install flock packages on a standard OS and not via a custom ISO. or PBR to work.
For example we are currently at fm-common-1.0-8.tis or sysinv-1.0-317.tis (for the master) as we approach the "stx-2.0" release for each commit to stx-fault a tarball would be generated: fm-common-1.0.0.dev<X> ... fm-common-1.0.0.dev<X+1>. When we release stx-2.0 the release tarball will be fm-common-1.2.0 and a patch will be fm-common-1.2.1. As we start the next release work will happen on fm-common-1.2.<z>.dev<X> ...
OpenDev has the infrastructure already via Zuul to generate and publish both release and intermediate development artifacts. We will need to make some policy decisions regarding how long we keep devlopment artifacts.
The justification for these changes are to ensure versioning that will work correctly for the various build tools of the different operating systems that maybe required for StarlingX to exist on. Every operating system has its own build recipe format to create packages to distribute the SW project across their users. Each package includes metadata that describes the package’s components, version, release, build and installation instructions among others. Without a proper version from the original source code , the distributions will have a hard time managing the packaging.
Please comment, this is a strawman to get input, after that the next step is to generate a proper Specification.
Thanks Sau!
[0] https://docs.openstack.org/pbr/3.1.0/semver.html [1] https://docs.openstack.org/pbr/latest/
Saul, thank you for sharing this. I like it a lot. I'm looking forward to seeing the spec.
Can we / should we extend our support of semantic versioning to the overall release numbering? We're already on that track - we are doing our 2.0 release now, which is an API level release from stx.2018.10 which we could consider our 1.0 release. If we call it 2.0.0, we'd be on track to continue following the versioning requirements going forward.
I think clearly communicating API changes to our users would be very helpful.
brucej
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Wednesday, May 15, 2019 11:29 AM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Flock Versioning for packaging
StarlingX Community:
Currently the versioning of the flock is mostly matching their internal API '1.0-<tis_patch_ver>.tis'. This is historical since the Upgrade process is a complete re-image of the disk from ISO and doesn't actually have to increase the version number between releases (other than maybe the tis_patch_ver).
Moving forward we need to consider using the OpenStack Semantic Versioning [0], and looking at PBR (Python Build Reasonableness) [1] to generate the version that is based on MAJOR.MINOR.PATCH where:
- MAJOR version when you make incompatible API changes - MINOR version when you add functionality in a backwards-compatible manner - PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
We understand the requirement that the Flock has across releases to preserve backward compatibility, likely the MAJOR will never change, but we should be considering that we bump the MINOR on each release and reset PATCH and bump PATCH based on doing a CVE, or required bug fix between releases.
To enable PBR, we would need to change the Python related setup to use setup.cfg with pbr, some of this work has started by Dean with Devstack related work. PBR won't address all packages since some are non-Python. We would also have to add versoining tags into git for PBR to work correctly. PBR can also help generate information for packaging.
During development, X.Y.Z.dev<N> or a "+g<hash>" is possible for builds. This is needed to during the development phase in order to track changes and help debug failures based on what packages are installed, it could also allow for independently updating of packages on a target system using standard packaging tools. This will be particularly important if we install flock packages on a standard OS and not via a custom ISO. or PBR to work.
For example we are currently at fm-common-1.0-8.tis or sysinv-1.0-317.tis (for the master) as we approach the "stx-2.0" release for each commit to stx-fault a tarball would be generated: fm-common-1.0.0.dev<X> ... fm-common-1.0.0.dev<X+1>. When we release stx-2.0 the release tarball will be fm-common-1.2.0 and a patch will be fm-common-1.2.1. As we start the next release work will happen on fm-common-1.2.<z>.dev<X> ...
OpenDev has the infrastructure already via Zuul to generate and publish both release and intermediate development artifacts. We will need to make some policy decisions regarding how long we keep devlopment artifacts.
The justification for these changes are to ensure versioning that will work correctly for the various build tools of the different operating systems that maybe required for StarlingX to exist on. Every operating system has its own build recipe format to create packages to distribute the SW project across their users. Each package includes metadata that describes the package’s components, version, release, build and installation instructions among others. Without a proper version from the original source code , the distributions will have a hard time managing the packaging.
Please comment, this is a strawman to get input, after that the next step is to generate a proper Specification.
Thanks Sau!
[0] https://docs.openstack.org/pbr/3.1.0/semver.html [1] https://docs.openstack.org/pbr/latest/
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
I have a little past experience with pbr, etc..
PBR is based off git tags.
The build tools currently do not preserve this git tag information when they prepare the src tarball for the src rpms. https://opendev.org/starlingx/root/src/branch/master/build-tools/build-pkg-s...
To handle this (today), the spec files are able to fake the PBR git tag through the PBR_VERSION env variable Ex: https://opendev.org/starlingx/config/src/branch/master/sysinv/cgts-client/ce...
If we update the build tool (and remove those variables from the spec files), then all python components in a particular repo will have the same version. We have some repos where there are multiple python components in the same repo.
The other (minor) thing to be aware of is the cost of querying the pbr version. Pbr makes use of pkg_resources, which processes all python files in order to determine entry_points, etc..
You incur this cost during import (only once per process). Typically about half a second in python2. I don't know about python3. I remember explicitly turning it off for cgtsclient, but the savings are begated if there are any other python imports (like keyring) that are also using pkg_resources.
Al
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: Wednesday, May 15, 2019 3:22 PM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Flock Versioning for packaging
Saul, thank you for sharing this. I like it a lot. I'm looking forward to seeing the spec.
Can we / should we extend our support of semantic versioning to the overall release numbering? We're already on that track - we are doing our 2.0 release now, which is an API level release from stx.2018.10 which we could consider our 1.0 release. If we call it 2.0.0, we'd be on track to continue following the versioning requirements going forward.
I think clearly communicating API changes to our users would be very helpful.
brucej
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Wednesday, May 15, 2019 11:29 AM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Flock Versioning for packaging
StarlingX Community:
Currently the versioning of the flock is mostly matching their internal API '1.0-<tis_patch_ver>.tis'. This is historical since the Upgrade process is a complete re-image of the disk from ISO and doesn't actually have to increase the version number between releases (other than maybe the tis_patch_ver).
Moving forward we need to consider using the OpenStack Semantic Versioning [0], and looking at PBR (Python Build Reasonableness) [1] to generate the version that is based on MAJOR.MINOR.PATCH where:
- MAJOR version when you make incompatible API changes - MINOR version when you add functionality in a backwards-compatible manner - PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
We understand the requirement that the Flock has across releases to preserve backward compatibility, likely the MAJOR will never change, but we should be considering that we bump the MINOR on each release and reset PATCH and bump PATCH based on doing a CVE, or required bug fix between releases.
To enable PBR, we would need to change the Python related setup to use setup.cfg with pbr, some of this work has started by Dean with Devstack related work. PBR won't address all packages since some are non-Python. We would also have to add versoining tags into git for PBR to work correctly. PBR can also help generate information for packaging.
During development, X.Y.Z.dev<N> or a "+g<hash>" is possible for builds. This is needed to during the development phase in order to track changes and help debug failures based on what packages are installed, it could also allow for independently updating of packages on a target system using standard packaging tools. This will be particularly important if we install flock packages on a standard OS and not via a custom ISO. or PBR to work.
For example we are currently at fm-common-1.0-8.tis or sysinv-1.0-317.tis (for the master) as we approach the "stx-2.0" release for each commit to stx-fault a tarball would be generated: fm-common-1.0.0.dev<X> ... fm-common-1.0.0.dev<X+1>. When we release stx-2.0 the release tarball will be fm-common-1.2.0 and a patch will be fm-common-1.2.1. As we start the next release work will happen on fm-common-1.2.<z>.dev<X> ...
OpenDev has the infrastructure already via Zuul to generate and publish both release and intermediate development artifacts. We will need to make some policy decisions regarding how long we keep devlopment artifacts.
The justification for these changes are to ensure versioning that will work correctly for the various build tools of the different operating systems that maybe required for StarlingX to exist on. Every operating system has its own build recipe format to create packages to distribute the SW project across their users. Each package includes metadata that describes the package’s components, version, release, build and installation instructions among others. Without a proper version from the original source code , the distributions will have a hard time managing the packaging.
Please comment, this is a strawman to get input, after that the next step is to generate a proper Specification.
Thanks Sau!
[0] https://docs.openstack.org/pbr/3.1.0/semver.html [1] https://docs.openstack.org/pbr/latest/
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
On 2019-05-15 20:18:49 +0000 (+0000), Bailey, Henry Albert (Al) wrote: [...]
The other (minor) thing to be aware of is the cost of querying the pbr version. Pbr makes use of pkg_resources, which processes all python files in order to determine entry_points, etc..
You incur this cost during import (only once per process). Typically about half a second in python2. I don't know about python3. I remember explicitly turning it off for cgtsclient, but the savings are begated if there are any other python imports (like keyring) that are also using pkg_resources.
[...]
As of PBR 2.1.0 the penalty can be deferred by separating your version query function out to a separate module and lazy-loading that only when the version info is actually needed, so depending on the software this could be an option (though if you want to log the version to a file at startup, not so much). The delay is also relative not only to system performance but also to the number of Python packages installed into the same context, so if this is happening in a venv or maybe a container with only a minimal number of Python packages installed then it can be almost instantaneous (but does get really slow if you have hundreds of Python dependencies installed).
For long-running processes it's usually not much of a concern anyway, but for some Python script you're forking repeatedly in rapid succession in a loop the overhead can quickly become crippling. We've toyed with the idea of caching pkg-resources lookups on disk, but then you get into the fun spot of deciding how to tell when you need to invalidate and refresh it.
On 2019-05-15 21:26:15 +0000 (+0000), Jeremy Stanley wrote: [...]
As of PBR 2.1.0 the penalty can be deferred by separating your version query function out to a separate module and lazy-loading that only when the version info is actually needed
[...]
Er, sorry, I meant before 2.1.0 you would work around it that way. Starting in 2.1.0 PBR lazy-imports pkg_resources only when it's being asked to query it, so you no longer need to separate your import of PBR out from your other modules.
On Wed, May 15, 2019 at 3:19 PM Bailey, Henry Albert (Al) Al.Bailey@windriver.com wrote:
If we update the build tool (and remove those variables from the spec files), then all python components in a particular repo will have the same version. We have some repos where there are multiple python components in the same repo.
As you note PBR and other OpenStack tooling has the assumption that everything in a git repo is related and is a single "thing". This could be changed, thus far it really has been easier to break out common components. We have to work around this in other areas too, such as maintaining multiple tox job definitions rather than using a single top-level tox.ini.
I think we need to break out more parts from the existing repos but within the same sub-project teams. I would start with either major pieces (inventory) or the small dependencies (tsconfig, fm-common/fm-core) and clients (cgts-client). I have done an experiment with cgts-client that took a couple of hours and is even mostly automated and maintains the git history.
dt
Sounds good Dean. I would be in favor of breaking some of these pieces into unique repos.
I like the idea of starting with cgtsclient (and its also an opportunity to rename it)
Al
-----Original Message----- From: Dean Troyer [mailto:dtroyer@gmail.com] Sent: Thursday, May 16, 2019 1:34 PM To: Bailey, Henry Albert (Al) Cc: Jones, Bruce E; Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Flock Versioning for packaging
On Wed, May 15, 2019 at 3:19 PM Bailey, Henry Albert (Al) Al.Bailey@windriver.com wrote:
If we update the build tool (and remove those variables from the spec files), then all python components in a particular repo will have the same version. We have some repos where there are multiple python components in the same repo.
As you note PBR and other OpenStack tooling has the assumption that everything in a git repo is related and is a single "thing". This could be changed, thus far it really has been easier to break out common components. We have to work around this in other areas too, such as maintaining multiple tox job definitions rather than using a single top-level tox.ini.
I think we need to break out more parts from the existing repos but within the same sub-project teams. I would start with either major pieces (inventory) or the small dependencies (tsconfig, fm-common/fm-core) and clients (cgts-client). I have done an experiment with cgts-client that took a couple of hours and is even mostly automated and maintains the git history.
dt
On Thu, May 16, 2019 at 1:23 PM Bailey, Henry Albert (Al) Al.Bailey@windriver.com wrote:
Sounds good Dean. I would be in favor of breaking some of these pieces into unique repos.
I like the idea of starting with cgtsclient (and its also an opportunity to rename it)
I don't want to hijack Saul's thread so I'll start a new one later, but I've started collecting dependencies and clients in [0] to collect thoughts about what to name them.
dt
[0] https://ethercalc.openstack.org/stx-repo-org
On 5/16/19 10:33 AM, Dean Troyer wrote:
On Wed, May 15, 2019 at 3:19 PM Bailey, Henry Albert (Al) Al.Bailey@windriver.com wrote:
If we update the build tool (and remove those variables from the spec files), then all python components in a particular repo will have the same version. We have some repos where there are multiple python components in the same repo.
As you note PBR and other OpenStack tooling has the assumption that everything in a git repo is related and is a single "thing". This could be changed, thus far it really has been easier to break out common components. We have to work around this in other areas too, such as maintaining multiple tox job definitions rather than using a single top-level tox.ini.
So, there have been a couple of replies to this thread, I would like to bring it back to the top of the queue for something to address in STX-3.0 release.
It seems we will need to add tagging back into our process for proper PBR support to ensure the flock get the correct version. If items need independent versioning then we may have to manually handle the versioning or possibly split them out as their own repo depending on the requirements.
I think we need to break out more parts from the existing repos but within the same sub-project teams. I would start with either major pieces (inventory) or the small dependencies (tsconfig, fm-common/fm-core) and clients (cgts-client). I have done an experiment with cgts-client that took a couple of hours and is even mostly automated and maintains the git history.
As we work on the openSUSE specfiles, it seems part of the way tsconfig works is to copy one directory into the Source RPM in Centos so everything is in the correct location (tsconfig/scripts is copied into tsconfig/tsconfig). Using the generic tarball [0] from stx-update, the scripts directory is not in the same place relative to the tsconfig setup.py.
[0] https://opendev.org/starlingx/update/archive/master.tar.gz
I hope this makes sense, I got into the weeds a little.
Sau!
dt
On Wed, May 15, 2019 at 2:22 PM Jones, Bruce E bruce.e.jones@intel.com wrote:
Can we / should we extend our support of semantic versioning to the overall release numbering? We're already on that track - we are doing our 2.0 release now, which is an API level release from stx.2018.10 which we could consider our 1.0 release. If we call it 2.0.0, we'd be on track to continue following the versioning requirements going forward.
I would rather not tie the overall integrated STX release to the individual components. It may be that the major versions align for a time but making that assumption is likely to bite us down the road.
I think clearly communicating API changes to our users would be very helpful.
It is but we really are not talking about APIs here (REST APIs anyway). APIs should be versioned separately from their implementation code. You ave at least 2 components (at a minimum 1 server and 1 or more clients) to each one and those components will likely not evolve at the same rate.
The "marketing version" (aka STX 2) we use for announcements, etc is the version of the "wrapper" or integrated ISO or whatever aggregate we ship in the future. It contains a number of versioned components, some themselves are wrappers (CentOS7.6 for example).
dt
On Wed, May 15, 2019 at 1:29 PM Saul Wold sgw@linux.intel.com wrote:
Moving forward we need to consider using the OpenStack Semantic Versioning [0], and looking at PBR (Python Build Reasonableness) [1] to generate the version that is based on MAJOR.MINOR.PATCH where:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards-compatible manner
- PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
We understand the requirement that the Flock has across releases to preserve backward compatibility, likely the MAJOR will never change, but we should be considering that we bump the MINOR on each release and reset PATCH and bump PATCH based on doing a CVE, or required bug fix between releases.
One thing to consider with regards to OpenStack versioning is that each project is versioned independently and the major version is increased at the integrated release at the end of the dev cycle. Also, sub-components are often completely independently versioned from the rest of the project (see neutron and neutron-lib for an example of this) and the major version is not automatically incremented.
For a variety of reasons (admittedly familiarity is big here) I want to move toward that kind of system. Unless there is great support for just jumping toward the full setup I think we can start incrementally by independently versioning the major components, which may involve splitting some things out of their existing home.
The part that I have the most personal interest in is splitting out the client and library (dependency) components and using a release model similar to OpenStack's cycle-with-intermediary[0]. This is what I have used for OpenStackClient and osc-lib and it lets us a) release as necessary for bug fixes, and b) still have a checkpoint that is known to be co-installable with the coordinated cycle release.
dt
[0] https://releases.openstack.org/reference/release_models.html#cycle-with-inte...
-- Dean Troyer dtroyer@gmail.com
participants (5)
-
Bailey, Henry Albert (Al)
-
Dean Troyer
-
Jeremy Stanley
-
Jones, Bruce E
-
Saul Wold