mirror of
https://git.proxmox.com/git/libgit2
synced 2025-04-30 19:28:36 +00:00
64 lines
2.8 KiB
Markdown
64 lines
2.8 KiB
Markdown
The maintainers of the libgit2 project believe that having a stable API
|
|
to program against is important for our users and the ecosystem - whether
|
|
you're building against the libgit2 C APIs directly, creating a wrapper to
|
|
a managed language, or programming against one of those managed wrappers
|
|
like LibGit2Sharp or Rugged.
|
|
|
|
Our API stability considerations are:
|
|
|
|
* Our standard API is considered stable through a major release.
|
|
|
|
* We define our "standard API" to be anything included in the "git2.h"
|
|
header - in other words, anything defined in a header in the `git2`
|
|
directory.
|
|
|
|
* APIs will maintain their signature and will not be removed within a
|
|
major release, but new APIs may be added.
|
|
|
|
* Any APIs may be marked as deprecated within a major release, but will
|
|
not be removed until the next major release (at the earliest). You
|
|
may define `GIT_DEPRECATE_HARD` to produce compiler warnings if you
|
|
target these deprecated APIs.
|
|
|
|
* We consider API compatibility to be against the C APIs. That means
|
|
that we may use macros to keep API compatibility - for example, if we
|
|
rename a structure from `git_widget_options` to `git_foobar_options`
|
|
then we would `#define git_widget_options git_foobar_options` to retain
|
|
API compatibility. Note that this does _not_ provide ABI compatibility.
|
|
|
|
* Our systems API is only considered stable through a _minor_ release.
|
|
|
|
* We define our "systems API" to be anything included in the `git2/sys`
|
|
directory. These are not "standard" APIs but are mechanisms to extend
|
|
libgit2 by adding new extensions - for example, a custom HTTPS transport,
|
|
TLS engine, or merge strategy.
|
|
|
|
* Additionally, the cmake options and the resulting constants that it
|
|
produces to be "systems API".
|
|
|
|
* Generally these mechanism are well defined and will not need significant
|
|
changes, but are considered a part of the library itself and may need
|
|
|
|
* Systems API changes will be noted specially within a release's changelog.
|
|
|
|
* Our ABI is only considered stable through a _minor_ release.
|
|
|
|
* Our ABI consists of actual symbol names in the library, the function
|
|
signatures, and the actual layout of structures. These are only
|
|
stable within minor releases, they are not stable within major releases
|
|
(yet).
|
|
|
|
* Since many FFIs use ABIs directly (for example, .NET P/Invoke or Rust),
|
|
this instability is unfortunate.
|
|
|
|
* In a future major release, we will begin providing ABI stability
|
|
throughout the major release cycle.
|
|
|
|
* ABI changes will be noted specially within a release's changelog.
|
|
|
|
* Point releases are _generally_ only for bugfixes, and generally do _not_
|
|
include new features. This means that point releases generally do _not_
|
|
include new APIs. Point releases will never break API, systems API or
|
|
ABI compatibility.
|
|
|