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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
<?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>
|
