Skip to content

V20VersionABIChanges

Jump to bottom
Ross Bencina edited this page Sep 9, 2014 · 23 revisions

DRAFT WORK IN PROGRESS

September 2014

h2. 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

h2. 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.

h2. Requirements (in no particular order)

The purpose of this section is to list requirements and uses for version API features. It is intended to be exhaustive so that we can assess interactions between requirements.

h3. 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: bq. "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'.)

h3. We should use "19" to refer to the current API revision

"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)

h3. A sane version number format that we can use to refer to releases. e.g. "20.0.1"

why? what is this used for? ??? what reasons have people given for wanting this?

It is desirable to also use this version number for code-based checks (compile time and runtime).

We should probably also encode whether a tarball is an RC or a final release in this version number (or at least in the version info string).

h3. 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]

h3. Provide a policy and a run-time mechanism that allows the client program to determine API/ABI compatibility when loading a shared library [desirable?]

E.g. allows the client program to fail if API/ABI version is not compatible. (this may simply mean matching ABI versions, or we may provide backward compatibility within a major version -- need to specify)

Answers question: can I use this shared library?

h3. Provide a policy and a run-time mechanism that allows the client program to determine API/ABI availability when loading a shared library [desirable?]

Answers question: 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

h3. 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."

h3. availability of SVN version number at runtime/ in compiled library

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

h3. releases should have SVN revision numbers associated with them and be tagged in the repository

h2. Misc Considerations

We need to establish a revision controlled document that describes 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 (when the ABI breaks?).

h2. 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.

h2. Proposals

h3. 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

h3. Version number scheme

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

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

h3. Version number API

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

Add new API in V20.

"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.

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

Remove version numbers from structs: https://www.assembla.com/spaces/portaudio/tickets/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?"

h2. Alternatives not taken

h2. Additional dependencies / related changes

h2. 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.)

h3. The repo needs to be structured to support merge requests (remove redundant/old top level repos).

We have 3 projects in one.

https://www.assembla.com/code/portaudio/subversion/nodes

I guess we should have had a trunk and branches at the root and put our projects under trunk.

Not sure what to do about that. I tried the suggested workaround and it seems to work but is clunky. Maybe some svn moves...

h2. References

  • #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

PortAudio

Clone this wiki locally