On Mon, 2016-08-01 at 03:23 -0400, Alexandre Demers wrote:
>
> Since I had no answer for now about my previous email, I'll assume the
> major version number to be the API/ABI compatibility number. With that,
> here is a patch to generate and install a pkg-config file for libpodofo.
>
> Please, note that the .pc file will only be created for system where
> pkg-config is available. I could have restricted it only to the OS, but
> than again pkg-config can be installed on mostly any OS. On the other
> hand, .pc file could be created and installed in all cases, so if
> wanted, this condition could be removed.
>
Hi,
I'm not a PoDoFo maintainer, but from my past experience, the API
stability is currently identified by the MAJOR.MINOR.MICRO version,
thus basically what it is right now.
Regarding the patch:
a) please send patches as attachments, different mail applications can
garble "patches" sent inline;
b) I would create the .pc file always personally;
c) does the patch expect any other changes being applied?
Bye,
zyx
Hi zyx,
Indeed, about the API backward compatibility, it seems as such. I've
found this very useful site yesterday which lists API/ABI backward
compatibility for many free libraries: http://upstream.rosalinux.ru/
One can find the results for PoDoFo between 0.5.0 and 0.9.3:
http://upstream.rosalinux.ru/versions/podofo.html
- Not proposing a "stable" number in the versioning scheme should be
avoided at all costs, otherwise programs need to be recompiled for every
"patch" increment to insure that it is still working as expected.
Example: at work, I'm on Archlinux, using Scribus-svn (thus compiled
directly on my system) for the added functionalities provided by the
latest dev version. When I needed Scribus, I had to recompile it for
that small patch increment.
Another example: Valve's Steam had many bugs reported on Linux when the
libnm team broke their API compatibility without having such a
versioning mechanism: Steam was relying on a given version, the number
thought to be representing the API compatibility had not been updated,
thus crashing Steam for many users that were using their native
libraries once they had received the latest libnm library. It is a
mechanism change that has to be implemented.
- I would at least suggest to use the minor number as the stable API
mecanism; patch number would then be used only for fixes. By going a bit
further, adding new functions, symbols, etc. is not a problem as long as
the available API/ABI is preserved. Thus, the minor number could be used
for that purpose instead and the major number increment would represent
something deeper (API/ABI incompatibility).
- PoDoFo could also use an odd/even minor number to indicate if the API
is stable or if this is a development version.
- Functions could be flagged as deprecated (webpage, doc, changelog or
even outputting a warning when used) if they were to be replaced/removed
in the next stable version after new ones had be introduced.
- Here are my toughts when reading about 0.5.0 being the latest
"stable", and than about 0.9.0 being refactored and enhanced: one should
ask himself why 0.5.0 was never promoted to an official 1.0.0 and 0.9.0
to a 2.0.0. The API/ABI is incompatible, podofo-base and podofo-doc
libraries were removed and merged in libpodofo and so on.
Major increment = API/ABI [in]compatibility
Minor increment = new features, API/ABI backward compatible
Patch increment = fixes, nothing added nor removed
Now, since we are at 0.9.4 and some patches have been merged since its
release, maybe it is time to create a 1.0.0 version, to add some
indications to the merge/development process for API/ABI backward
compatibility, maybe even to name someone in charge of merging patches
for a given branch once a release is out, etc. From there, 1.0.0 would
be the new stable release and a branch would be created. Then, 1.0.X
would be created along the way for fixes and trunk would be used to add
new features until a given point where 1.Y.0 would be released and
branched. Later, to initiate major changes, a new branch would be
created (in-the-way-to-2.0.0) that would become 2.0.0 when ready, etc.
At the rate where the releases are created, I think that would be the
best way to go (two years between 0.9.3 and 0.9.4, a year between 0.9.2
and 0.9.3, almost 2 years between 0.9.1 and 0.9.2). To ensure nothing is
broken between Minor or Patch increments, we could run something like
ABI compliance checker.
a) I'm sorry about the patch attachment/inline, I'm used to the mesa,
dri and kernel way of doing this: all emails are sent as plain text,
encoded in UTF-8. Patches are also sent inlined as plain text. It is
easier to read, reply and comment for anybody, easier to search for and
by using plain text in UTF-8, there is no problem to merge them.
PoDoFo's community could have a look at "git-send-email" on that matter.
However, if PoDoFo prefers attachments, that's what I'll use next time.
b) noted, comments are appreciated. I've been thinking about it for the
last few days.
c) no other change needed. The CMakeLists.txt changes take care of
creating and installing the file; the .pc.in <http://pc.in> is used as
an input file (template) to create a personalized .pc file according to
the system or distribution at build time. It may need to be adjusted
after statuating about the API/ABI backward compatibility scheme VS
versioning though.
Cheers,
Alexandre Demers
------------------------------------------------------------------------------
_______________________________________________
Podofo-users mailing list
Podofo-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/podofo-users
