-
Notifications
You must be signed in to change notification settings - Fork 304
V20VersionABIChanges
DRAFT WORK IN PROGRESS
September 2014
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
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.
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.
"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'.)
The version number on the tarball should be the same as the one in the code.
"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)
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).
e.g. 20.0.1 might be encoded as 200001
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
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
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
A requirement on the release process (possibly already in place)
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).
As soon as we change the ABI we bump the major version number to 20. We won't be supporting v19 after that.
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
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.
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.
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?"
"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.)
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...
-
#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