1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
<?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="de">
<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>Abwärtskompatibilität in APIs</desc>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>Mario Blättermann</mal:name>
<mal:email>mario.blaettermann@gmail.com</mal:email>
<mal:years>2016, 2018</mal:years>
</mal:credit>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>Christian Kirbach</mal:name>
<mal:email>christian.kirbach@gmail.com</mal:email>
<mal:years>2016, 2020</mal:years>
</mal:credit>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>Stefan Melmuk</mal:name>
<mal:email>stefan.melmuk@gmail.com</mal:email>
<mal:years>2018</mal:years>
</mal:credit>
<mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
<mal:name>Tim Sabsch</mal:name>
<mal:email>tim@sabsch.com</mal:email>
<mal:years>2021</mal:years>
</mal:credit>
</info>
<title>API-Stabilität</title>
<synopsis>
<title>Zusammenfassung</title>
<list>
<item><p>Bestimmen Sie API-Stabilitätsgarantien für Ihr Projekt. (<link xref="#stability"/>)</p></item>
<item><p>Stellen Sie sicher, dass bei API-Änderungen auch die entsprechende Versionsnummer geändert wird. (<link xref="#versioning"/>)</p></item>
</list>
</synopsis>
<section id="api-and-abi">
<title>API und ABI</title>
<p>Auf höherer Ebene ist eine API (<em>Application Programming Interface</em>) die Schnittstelle zwischen zwei Komponenten, die gegeneinander entwickelt werden. Sie ist nah verwandt mit der ABI (<em>Application Binary Interface</em>), der Binärschnittstelle zur Laufzeit. Eine Schnittstelle bestimmt die verschiedenen Möglichkeiten, wie andere Komponenten mit einer Komponente interagieren können. Im Normalfalls stellen die C-Header einer Bibliothek die API und die kompilierten Symbole die ABI einer Bibliothek dar . Der Unterschied zwischen API und ABI kommt vor allem durch die Kompilation des Quelltextes: so befinden sich in einer C-Headerdatei gewisse Sachen wie <code>#define</code>-Anweisungen, die zur Änderung der API führen können, ohne dass sich die ABI ändert. In der Praxis können die Unterschiede zwischen API und ABI aber vernachlässigt werden, weil sie meistens austauschbar behandelbar sind.</p>
<p>Beispiele für API-inkompatible Änderungen einer C-Funktion wären das Hinzufügen eines neuen Parameters, Ändern des Rückgabetyps einer Funktion oder die Entfernung eines Parameters.</p>
<p>Aber auch andere Teile eines Projekts können eine API darstellen. Wenn sich ein Daemon über D-Bus exponiert, stellen die dort exportierten Schnittstellen eine API dar. Wenn eine C-API in einer höheren Programmiersprache durch Verwendung von GIR offengelegt wird, dann stellt die GIR-Datei eine andere Form von API dar — wenn sie sich ändert, muss sich auch der gesamte Code ändern, der sich darauf bezieht.</p>
<p>Andere Beispiele von eher ungewöhnlichen APIs sind Konfigurationsdateiorte und -formate und GSettings-Schemas. Änderungenen an diesen könnten es erforderlich machen, dass sich auch Code ändern muss, der eine Bibliothek verwendet.</p>
</section>
<section id="stability">
<title>Stabilität</title>
<p>API-Stabilität bezieht sich darauf, inwiefern ein Projekt garantiert, dass sich seine API nur auf bestimmten Wege verändern oder auch nicht mehr verändern wird. Allgemein wird eine API dann als sicher betrachtet, wenn sie sich auf Abwärtskompatibilität festlegt; eine API könnte sich aber auch darauf festlegen, instabil oder aufwärtskompatibel zu sein. Der Zweck einer API-Stabilitätsgarantie ist es anderen zu ermöglichen, ein Projekt in ihrem Code zu verwenden, ohne dass sie sich ständig Sorgen machen müssen, ihren Code dauernd ändern zu müssen, um API-Änderungen zu berücksichtigen. Eine typische API-Stabilitätsgarantie wäre, dass Code, der gegen eine bestimmte Version einer Bibliothek kompiliert wurde, ohne Probleme auch mit zukünftigen Versionen dieser Bibliothek mit derselben Hauptversionsnummer laufen wird — oder auch, dass Code, der gegen einen Daemon programmiert wurde, auch auf zukünftigen Versionen mit derselben Hauptversionsnummer laufen wird.</p>
<p>Es ist möglich, verschiedene Ebenen von API-Stabilitätsgarantien auf Komponententen innerhalb eines Projekts anzubringen. Zum Beispiel könnten die Kernfunktionalitäten einer Bibliothek stabil sein und deshalb auch deren API unverändert bleiben, während die neueren, sekundäreren Funktionenen instabil bleiben und sich sehr stark ändern dürfen, solange bis das richtige Design gefunden wurde und sie dann als sicher gekennzeichnet werden könnten.</p>
<p>Im Allgemeinen werden verschiedene Typen der Stabilität bezeichnet:</p>
<terms>
<item>
<title>Instabil (<em>unstable</em>)</title>
<p>Die API kann sich ändern oder in der Zukunft geändert werden.</p>
</item>
<item>
<title>Backwards compatible (Abwärtskompatibilität)</title>
<p>Es sind nur solche Änderungen zulässig, die einem Code, der gegen die unmodifizierte API kompiliert wird, erlauben, auch mit der geänderten API zu laufen (z.B. können keine Funktionen entfernt werden).</p>
</item>
<item>
<title>Forwards compatible (Aufwärtskompatibilität)</title>
<p>Es sind nur solche Änderungen zulässig, die einem Code, der gegen die modifizierte API kompiliert wird, erlauben, auch mit der vorherigen API zu laufen (z.B. können keine Funktionen hinzugefügt werden).</p>
</item>
<item>
<title>Gänzlich unveränderlich (<em>totally stable</em>)</title>
<p>Es sind keine Änderungen an der API erlaubt, nur an deren Implementation.</p>
</item>
</terms>
<p>Üblicherweise verpflichtet sich ein Projekt zur Abwärtskompatibilität, wenn es meint, eine API wäre 'stabil' (<em>stable</em>). Die wenigsten Projekte verpflichten sich zu einer gänzlichen Unveränderlichkeit (<em>total stability</em>), weil es fast die ganze weitere Entwicklung des Projektes verhindern würde.</p>
</section>
<section id="versioning">
<title>Versionierung</title>
<p>API-Stabilitätsgarantien sind eng mit der Versionierung des Projekts verknüpft; das betrifft sowohl die Paket- als auch die Libtool-Versionierung. Letztere dient ausschließlich dem Zweck, die API-Stabilität zu überwachen, sie wird detailliert in <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link> oder <link xref="versioning"/> erklärt.</p>
<p>Paketversionierung (<em>major.minor.micro</em>) ist eng mit API-Stabilität verknüpft: typischerweise, wird die Hauptversionsnummer (<em>major version number</em>) erhöht, wenn eine Änderung nicht mehr abwärtskompatibel ist (zum Beispiel wenn Funktionen umbenannt, Parameter geändert oder Funktionen entfernt werden). Die Nebenversionsnummer (<em>minor version number</em>) wird erhöht, wenn eine Änderung nicht mehr aufwärtskompatibel ist (zum Beispiel wenn eine neue öffentliche API hinzugefügt wird). Die dritte Versionsnummer (<em>micro version number</em>) wird erhöht, wenn die Code-Änderungen ohne Änderung der API möglich sind. Siehe <link xref="versioning"/> für weitere Informationen.</p>
<p>API-Versionierung ist genauso wichtig für D-Bus-Schnittstellen und GSettings-Schemas (falls sie sich häufiger ändern) wie für C-Programmierschnittstellen. Siehe die <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">Dokumentation der D-Bus-API-Versionierung</link> für Details.</p>
<p>Die Stabilität von GIR-Schnittstellen orientiert sich normalerweise an der C-API-Stabilität, weil sie aus der C-API generiert werden. Eine Komplikation dabei ist, dass deren Stabilität zusätzlich noch von der Version der GObject-Introspektion abhängt, die zur Generierung der GIR verwendet wurde. Die neueren Versionen von GIR haben sich nicht so sehr geändert, weshalb das kein großer Grund zur Besorgnis sein sollte.</p>
</section>
<section id="external-links">
<title>Externe Links</title>
<p>Das Thema API-Stabilität wird in den folgenden Artikeln behandelt:</p>
<list>
<item><p><link href="https://de.wikipedia.org/wiki/Programmierschnittstelle">Wikipedia-Seite zu Programmierschnittstellen</link></p></item>
<item><p><link href="https://de.wikipedia.org/wiki/Bin%C3%A4rschnittstelle">Wikipedia-Seite zu Binärschnittstellen</link></p></item>
<item><p><link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">Dokumentation zur Versionierung der D-Bus-API</link></p></item>
</list>
</section>
</page>
|
