Skip to content

V20VersionABIChanges

Ross Bencina edited this page Nov 19, 2020 · 23 revisions

DRAFT WORK IN PROGRESS

September 2014

Summary

This page is about changes to the version API. We are in the process of revising this API for PA V20. See the References section at the end for links to mailing list discussions and tickets.

We will move to a "traditional" dotted version number scheme with real releases. Phil notes that "there are some bugs that need fixing and we have not implemented all the things that we have planned. We should continue to work toward those goals.":http://music.columbia.edu/pipermail/portaudio/2014-February/015720.html However that should not prevent us for moving from date-stamped snapshots to numbered releases.

There are at least two important ML threads on this topic:

"New stable release? (Jan-Feb 2014)": http://music.columbia.edu/pipermail/portaudio/2014-January/015570.html

"trying to create Assembla merge request (Feb 2014)": http://music.columbia.edu/pipermail/portaudio/2014-February/015824.html

Existing V19 version interfaces

The current public "official" PA V19 source version numbering is based on the timestamp of the stable or nightly tarball, e.g. pa_stable_v19_20140130.tgz

V19 API provides the following two functions to query the API version (see "portaudio.h":http://portaudio.com/docs/v19-doxydocs/portaudio_8h.html, originally added via "this proposal":http://www.portaudio.com/docs/proposals/018-VersionInformationInterface.html):

int 	Pa_GetVersion (void)
const char * Pa_GetVersionText (void)

Note: Pa_GetVersion has so far always returned 1899 and is hence not very useful. The content of Pa_GetVersionText() is not strictly specified and could be changed or improved.

Some PA structs have a structVersion field. These structVersion fields have not been consistently updated when structs were modified -- therefore they are not a very reliably mechanism.

The following structs contain structVersion fields:

"PaHostApiInfo":http://portaudio.com/docs/v19-doxydocs/structPaHostApiInfo.html "PaDeviceInfo":http://portaudio.com/docs/v19-doxydocs/structPaDeviceInfo.html "PaStreamInfo":http://portaudio.com/docs/v19-doxydocs/structPaStreamInfo.html

These structs don't:

"PaHostErrorInfo":http://portaudio.com/docs/v19-doxydocs/structPaHostErrorInfo.html "PaStreamParameters":http://portaudio.com/docs/v19-doxydocs/structPaStreamParameters.html "PaStreamCallbackTimeInfo":http://portaudio.com/docs/v19-doxydocs/structPaStreamCallbackTimeInfo.html

Host-API specific data structures may also have some kind of versioning field. e.g PaAsioStreamInfo has a size field rather than a structVersion field:

"PaAsioStreamInfo":http://portaudio.com/docs/v19-doxydocs/structPaAsioStreamInfo.html

TODO: review other host-API specific structs.

Removal of struct version fields is covered in issue #172.

Requirements (in no particular order)

This section lists requirements and uses-cases for version API features. It is intended to be exhaustive so that we can assess interactions between requirements. Some of these requirements need-not be addressed immediately.

A regular release schedule with actual releases (not just snapshots).

"Graham Goode explains a number of points in this post":http://music.columbia.edu/pipermail/portaudio/2014-January/015588.html

He writes: "from a users perspective what I am trying to communicate is - with this snapshot release please use a release number and not just a snapshot-date. Make it an official release with a version number so there can be release announcements and so that we can reference a defined PortAudio release in our release notes as well."

The main points are:

  • Having official release versions allows to formally state that things have been fixed (sends a clearer message about which version to use).
  • Increasing version numbers send a clear message that progress has been made (timestamps: not so much).
  • Downstream open source projects need a version identifier they can use to point people at who want to build from source. Potentially they could use a newer minor release if there was a policy about when breaking changes happen.
  • Announcing a release version would allow package managers of the various Linux Distributions to package the latest code.
  • Provide a framework for regular releases (e.g. bug fixes can be rolled into a minor release every 6 months, major release when things are 'complete'.)

Version numbers should be harmonised across all media

The version number on the tarball should be the same as the one in the code.

Use "19" to refer to the current API revision (as of start 2014)

"Phil starts the discussion about exactly how to number the current releases here":http://music.columbia.edu/pipermail/portaudio/2014-February/015720.html (this is also the beginning of the discussion about the actual version number format to use)

Use sane version number format that we can use to refer to releases.

e.g. "20.0.1"

It is desirable to also use this version number for code-based checks, i.e. compile-time and run-time.

Question: we could also encode whether a tarball is an RC or a final release in this version number (or at least in the version info string).

Have a single increasing number that can be used for comparisons in the code.

e.g. 20.0.1 might be encoded as 200001

An API for retrieving the version number of the current executing PortAudio

Allows the user of a program to report running version for debugging [must-have]

This may take three forms, possibly only the first is critical

  • A single integer
  • A struct with the unpacked version fields
  • A string

Provide a policy and a run-time mechanism that allows the client program to determine API/ABI compatibility when loading a shared library

Allow the client program to detect whether the API/ABI version is compatible at runtime. This may simply mean matching ABI versions, or we may provide backward compatibility within a major version. We need to specify what guarantees we make regarding API/ABI breakage. We could adopt the Linux model "as described by Alan here":http://music.columbia.edu/pipermail/portaudio/2014-February/015728.html

Allows client code to answer the following question(s):

  • Can I use this version of the library?

Provide a policy and a run-time mechanism that allows the client program to determine API/ABI availability when loading a shared library

Answers questions:

  • does this struct have the expected format?
  • does it have an expected field?

Considerations:

  • function signatures (number and types of params and return values)
  • layout of structs
  • availability of fields in structs

Compile-time macros for testing the version number

Allows conditional compilation of client code so that it uses PA features only if they are available and/or allows conditional compilation of clients against multiple incompatible PA APIs.

"Users should be able to use Pa_GetVersion() or Pa_GetVersionInfo() to determine the ABI (i.e. it should be usable in place of the old buggy struct version fields."

More discussion here in ticket #173

SVN version number should be queryable at runtime

Assists with PA developers debugging.

Alan notes: "A date tag is OK, but it is a problem that the svn version is not also available in the compiled library, and this discussion has already taken place, but without resolution. I would like to see it always there as the master record of the code.": http://music.columbia.edu/pipermail/portaudio/2014-February/015728.html

Releases should have SVN revision numbers associated with them and be tagged in the repository

A requirement on the release process (possibly already in place)

Policy Considerations

We need to establish a revision controlled document that documents ABI changes when they are made (ABICHANGES.txt ?)

We need a policy about when ABI changes will be made (major/minor version number increments)

We need a clear version migration path. At what point do we call this V20 (probably when the ABI breaks, see below).

Decisions that have already been made

As soon as we change the ABI we bump the major version number to 20. We won't be supporting v19 after that.

Proposals (Unconfirmed)

V19 to V20 transition

The current API and ABI should be frozen as-is and called major version "19." When we break the ABI or API we'll change to V20. To be specific: no breaking changes will be made at all for V19, not even "simple" or "minimal" changes.

We may move to V20 very soon (and hence break ABI/API) .

We will make a branch for maintaining V19, but we don't have any plans to support V19 once we release a V20 build.

"Transition discussion starts here":http://music.columbia.edu/pipermail/portaudio/2014-February/015799.html

Version number scheme

Phil's proposal:http://music.columbia.edu/pipermail/portaudio/2014-February/015720.html

I think we should use a common version number scheme based on major, 
minor and revision numbering.

Major is bumped when the API changes or significant features are added.
Minor is bumped when lots of changes are made.
Revision is bumped when only minor changes are made.

We could label the releases as follow:

V19.0.0 - 12/7/2007, first release with V19 API so we bump "major"
V19.1.0 - 3/26/2011
V19.1.1 - 11/21/2011
V19.2.0 - 1/30/2014, our most recent "snapshot"

The V19 release that has all the bugs fixed might be something like 
V19.7.3. If we later find and fix a bug then we can put out V19.7.4.

When do we "release" code? I think we should release when we have a 
stable version that is better than the last stable version. We cannot 
wait for perfect code because it will never happen.

Are you OK with this compound version number?

#define VERSION ((MAJOR<<16) + (MINOR<<8) + REVISION)

"Alan's summary of the Linux version number landscape very important information, also one of the summing-up emails in that thread":http://music.columbia.edu/pipermail/portaudio/2014-February/015728.html

We need to decide exactly what policy we adopt regarding the meaning of the version numbers.

Version number API

Retain Pa_GetVersion() as a minimal single version number API. Don't deprecate it (was previously suggested).

Add new API in V20 that supports split numbers and SVN revision (what happens if we switch to Git?)

"Back in 2008 Ross proposed":http://music.columbia.edu/pipermail/portaudio/2008-February/008347.html

PaVersionInfo{
    int majorVersion;
    int minorVersion;
    int buildNumber;
    int svnRevision;
    const char *versionText;
};

const PaVersionInfo* Pa_GetVersionInfo();

We need to keep Pa_GetVersion() to have a single number for comparison, and also because it's the only way to version the PaVersionInfo struct.

Have only a single ABI version, not per-struct version info.

Remove version numbers from structs: #172

The proposal is not to add struct length fields, but I think this needs to at least be considered -- RB

bq. "I can see the value in having struct sizes too. Should we consider that? The main down side I see is that it will force everyone to update their code, for the benefit of us /maybe/ adding fields to the end. It kind of gives us two revision mechanisms: (1) increase struct length to add optional fields, (2) bump major version number to break ABI any way we like (also supports adding fields if clients know about the ABI changes). Do we need 2 mechanisms?"

Proposed Immediate action (subject to review)

"Phil drew the following conclusions (Ross agrees)": http://music.columbia.edu/pipermail/portaudio/2014-February/015810.html

  • We stop releasing anything called V19. Make the needed API/ABI changes (including fixing all the version stuff, see below, release it as V20.0.0. Continue development as we are now. The folks who want to call the current code "V19" can continue doing so. They can consider the 20140130 snapshot as the "final V19 release". Officially, we will just skip V19 and go to V20.
  • Let's keep trunk-stable.
  • Let's just make a V19 branch in case we ever need to patch it. We don't have to patch it. It just gives us the option.

Phil proposed these steps:

#1 Create a "V19" branch and then just leave it. Declare it deprecated. #2 First change in V20 is to implement version numbering as 20.0.0. #3 Follow up with all the API changes. #4 Create a stable snapshot of "V20.0.x".

(Alternatively we could add the version number changes, then do one last V19 release.)

References

  • #173 "Improved API library version API":#173

  • #172 "Remove structVersion field from PaHostApiInfo, PaDeviceInfo and PaStreamInfo":#172

  • #174 "[META] ABI/API changes before V19 final release":#174

  • #58 API calling convention and pack
  • #169 Portaudio should expose host API specific stream information
  • #172 Remove structVersion field from PaHostApiInfo, PaDeviceInfo and PaStreamInfo
  • #173 Improved API library version API
  • #225 PA should expose host API specific device information
Clone this wiki locally