librelist archives

« back to archive

Re: The Great API Renaming of 2012

Re: The Great API Renaming of 2012

From:
Ben Straub
Date:
2012-11-28 @ 18:19
I've just merged in a series of commits that will be rather painful to
adjust to.

Libgit2 has always been alpha software. As such, we've played fast and
loose with structural changes and renaming things. And that's okay for
alpha software, but not if it's been released, and other software depends
on it.

The core team recently met to discuss what we still need in order to really
think of libgit2 as 1.0 software. One of the things was API consistency; we
didn't have a set of guidelines we follow when creating new APIs, and once
1.0 hits, we want to make fairly strong [SemVer] guarantees about breaking
changes.

[SemVer]: http://semver.org/

To that end, we came up with some [guidelines], and systematically applied
them to the API. That work just got merged into the `development` branch,
and it has quite a few changes to the exported headers that binding authors
should be aware of.

[guidelines]:
https://github.com/libgit2/libgit2/blob/development/CONVENTIONS.md

In particular:

* Any usage of `git_diff_*` should be inspected; the parameters have been
reordered for quite a few of these calls.
* The `git_reference_*` group had a lot of renaming, including the
following troublesome pair:
  * `git_reference_target` -> `git_reference_symbolic_target`
  * `git_reference_oid` -> `git_reference_target`

We know this will cause some short-term problems, but we feel that now is
the time to make these changes. It'll hurt a lot more later.

– Ben