<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="api-stability" xml:lang="sv">

  <info>
    <link type="guide" xref="index#maintainer-guidelines"/>

    <credit type="author copyright">
      <name>Philip Withnall</name>
      <email its:translate="no">philip.withnall@collabora.co.uk</email>
      <years>2015</years>
    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Bakåtkompatibilitet i API:er</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Anders Jonsson</mal:name>
      <mal:email>anders.jonsson@norsjovallen.se</mal:email>
      <mal:years>2018</mal:years>
    </mal:credit>
  </info>

  <title>API-stabilitet</title>

  <synopsis>
    <title>Sammanfattning</title>

    <list>
      <item><p>Definiera garantier för API-stabilitet för ditt projekt. (<link xref="#stability"/>)</p></item>
      <item><p>Säkerställ att versionsnummer ändras på lämpligt sätt då API ändras. (<link xref="#versioning"/>)</p></item>
    </list>
  </synopsis>

  <section id="api-and-abi">
    <title>API och ABI</title>

    <p>
      At a high level, an API – <em>Application Programming Interface</em> – is
      the boundary between two components when developing against them. It is
      closely related to an ABI – <em>Application Binary Interface</em> – which
      is the boundary at runtime. It defines the possible ways in which other
      components can interact with a component. More concretely, this normally
      means the C headers of a library form its API, and compiled library
      symbols its ABI. The difference between an API and ABI is given by
      compilation of the code: there are certain things in a C header, such as
      <code>#define</code>s, which can cause a library’s API to change without
      changing its ABI. But these differences are mostly academic, and for all
      practical purposes, API and ABI can be treated interchangeably.
    </p>

    <p>Exempel på API-inkompatibla ändringar till en C-funktion skulle vara att lägga till en ny parameter, ändra funktionens returtyp eller att ta bort en parameter.</p>

    <p>
      However, many other parts of a project can form an API. If a daemon
      exposes itself on D-Bus, the interfaces exported there form an API.
      Similarly, if a C API is exposed in higher level languages by use of
      GIR, the GIR file forms another API — if it changes, any higher level
      code using it must also change.
    </p>

    <p>Andra exempel på mer ovanliga API:er är platser och format för konfigurationsfiler, och GSettings-scheman. Alla ändringar till dessa kan kräva att kod som använder ditt bibliotek behöver ändras.</p>
  </section>

  <section id="stability">
    <title>Stabilitet</title>

    <p>
      API stability refers to some level of guarantee from a project that its
      API will only change in defined ways in the future, or will not change at
      all. Generally, an API is considered ‘stable’ if it commits to
      backwards-compatibility (defined below); but APIs could also commit to
      being unstable or even forwards-compatible. The purpose of API stability
      guarantees is to allow people to use your project from their own code
      without worrying about constantly updating their code to keep up with
      API changes. Typical API stability guarantees mean that code which is
      compiled against one version of a library will run without problems
      against all future versions of that library with the same major version
      number — or similarly that code which runs against a daemon will
      continue to run against all future versions of that daemon with the same
      major version number.
    </p>

    <p>Det är möjligt att tillämpa olika nivåer av API-stabilitet till komponenter i ett projekt. Till exempel kan de centrala funktionerna i ett bibliotek vara stabila, och därför kan deras API lämnas oförändrat i framtiden; mindre centrala funktioner skulle kunna lämnas instabila och tillåtas att förändras mycket till dess att rätt design hittats, och vid den tidpunkten skulle de kunna markeras att vara stabila.</p>

    <p>Flera typer av stabilitet som vanligen tas i beaktande:</p>
    <terms>
      <item>
        <title>Instabilt</title>
        <p>API:t kan ändras eller tas bort i framtiden.</p>
      </item>
      <item>
        <title>Bakåtkompatibelt</title>
        <p>Endast ändringar som tillåter kod som kompilerats mot det oförändrade API:t att fortsätta köra mot det ändrade API:t tillåts (till exempel kan inte funktioner tas bort).</p>
      </item>
      <item>
        <title>Framåtkompatibelt</title>
        <p>Endast ändringar som tillåter kod som kompilerats mot det ändrade API:t att köra mot det oförändrade API:t tillåts (till exempel kan inte funktioner läggas till).</p>
      </item>
      <item>
        <title>Fullständigt stabilt</title>
        <p>Inga ändringar tillåts i API:t, endast i implementationen.</p>
      </item>
    </terms>

    <p>Typiskt binder sig projekt till bakåtkompatibilitet då de säger att ett API är ”stabilt”. Väldigt få projekt binder sig till fullständig stabilitet då det skulle förhindra nästan all vidare utveckling av projektet.</p>
  </section>

  <section id="versioning">
    <title>Versionering</title>

    <p>API-stabilitetsgarantier är starkt länkade till projektversionering; både paketversionering och libtool-versionering. Libtool-versionering existerar enbart för syftet att följa ABI-stabilitet, och förklaras i detalj i <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link> eller <link xref="versioning"/>.</p>

    <p>
      Package versioning (<em>major.minor.micro</em>) is strongly linked to API
      stability: typically, the major version number is incremented when
      backwards-incompatible changes are made (for example, when functions are
      renamed, parameters are changed, or functions are removed). The minor
      version number is incremented when forwards-incompatible changes are
      made (for example, when new public API is added). The micro version
      number is incremented when code changes are made without modifying API.
      See <link xref="versioning"/> for more information.
    </p>

    <p>API-versionering är precis lika viktig för D-Bus-API:er och GSettings-scheman (om de kan förväntas ändras) som för C-API:er. Se <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">dokumentationen om versionering för D-Bus-API:er</link> för detaljer.</p>

    <p>För GIR-API:er följer stabiliteten typiskt stabiliteten hos C-API:t eftersom de genereras från C-API:t. En komplexitet är att deras stabilitet dessutom beror på versionen av gobject-introspection som använts vid generering av GIR, men senare versioner har inte ändrats mycket, så detta är inget större problem.</p>
  </section>

  <section id="external-links">
    <title>Externa länkar</title>

    <p>Ämnet API-stabilitet täcks i följande artiklar:</p>
    <list>
      <item><p><link href="https://en.wikipedia.org/wiki/Application_programming_interface">Wikipedia-sidan om API:er</link></p></item>
      <item><p><link href="https://en.wikipedia.org/wiki/Application_binary_interface">Wikipedia-sidan om ABI:er</link></p></item>
      <item><p><link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">D-Bus API-versionsdokumentation</link></p></item>
    </list>
  </section>
</page>
