thodg/libgit2/docs/api-stability.md

• Show log

  Commit

• Hash : 240c195f
  Author :
  Date : 2022-01-02T08:19:45
  

  docs: document our API/ABI stability stance

Download

Source

• docs/api-stability.md

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

Download