<?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="ko">

  <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>API 하위 호환성</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>조성호</mal:name>
      <mal:email>shcho@gnome.org</mal:email>
      <mal:years>2016, 2017.</mal:years>
    </mal:credit>
  </info>

  <title>API 안정성</title>

  <synopsis>
    <title>요약</title>

    <list>
      <item><p>프로젝트의 API 안정성 보증을 정의합니다. (<link xref="#stability"/>)</p></item>
      <item><p>API를 바꿀 때 적당한 버전 숫자로 바꾸었는지 확인합니다. (<link xref="#versioning"/>)</p></item>
    </list>
  </synopsis>

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

    <p>상위 계층의 API(<em>Application Programming Interface</em>)는 API 및 ABI를 개발할 때 두 요소 간의 경계선상에 있고, 실행 시점에 따른 ABI(<em>Application Binary Interface</em>)와 밀접한 관계가 있습니다. ABI는 서로 동작할 수 있는 구성 요소의 관계를 정합니다. 좀 더 확실하게 말하자면, 라이브러리의 C 헤더가 API를 구성하고, 컴파일한 라이브러리는 ABI를 규정합니다. API와 ABI의 차이점은 코드 컴파일의 차이입니다. <code>#define</code>와 같은 C 헤더의 구성 요소는 ABI를 바꾸지 않고 라이브러리의 API를 바꿀 수 있습니다. 허나, 주로 이론적 차이가 있으며 대부분의 실제 목적에 있어서는 API와 ABI를 서로 바꾸어가며 생각할 수 있습니다.</p>

    <p>API 비호환성에 대해, 새 매개변수를 추가하도록 C 함수를 바꾸거나, 함수의 반환 형식을 바꾼다든지, 매개변수를 제거하는 예를 들 수 있습니다.</p>

    <p>하지만, 대부분의 프로젝트에서는 API를 구성할 수 있습니다. 데몬 자체를 D-Bus에 노출한다면 API를 구성하도록 인터페이스를 내보냅니다. 동일한 관점에서, C API를 GIR로 고 수준 언어에 노출한다면, GIR 파일에서 다른 API를 구성합니다. 이게 바뀌면 API를 사용하는 고 수준 언어 코드도 바꿔야합니다.</p>

    <p>좀 더 드문 API 예를 들자면, 설정 파일 위치, 설정 파일 형식, GSettings 스키마가 있습니다. 이 설정의 값을 바꾸면 라이브러리를 사용하는 코드를 바꿔야 할 수 있습니다.</p>
  </section>

  <section id="stability">
    <title>안정성</title>

    <p>API 안정성이란 프로젝트 API를 나중에 지정한 방식으로 바꾸거나 바꾸지 않을 프로젝트 일부 레벨의 보장을 의미합니다. 보통 API가 `안정적`이다 라고 한다면 (아래에 정의한 바와 같이) 하위 호환성을 지키며 커밋했을 경우입니다. 하지만 API에는 불안정하거나 상위 버전 호환성을 지니는 내용이 들어갈 수도 있습니다. API 안정성의 목적은 API가 바뀌어도 코드를 꾸준히 업데이트 하는 일을 걱정하지 않고 있는 코드 자체만으로 사람이 사용할 수 있게 보장하는 것입니다. 보통 API 안정성은 어떤 버전의 라이브러리에 대해 컴파일한 코드가 동일한 주 버전을 지닌 이후 버전의 라이브러리에서도 문제없이 동작함을 의미하거나, 동일한 주 버전의 데몬이 앞으로 나올 버전에서도 계속 동작하는 코드와 비슷한 의미를 지니고 있습니다.</p>

    <p>프로젝트에서 구성 요소에 대해 제각기 다른 수준의 API 안정성을 적용할 수 있습니다. 예를 들어 라이브러리의 핵심 함수는 안정적이어야 하며, 나중에도 API를 바꾸지 않은 상태로 두어야 합니다. 반면에 덜 핵심적이며 새로운 함수는 불완전한 상태로 둘 수 있고, 적절한 설계 관점에 도달하여 안정적인 상태로 간주하기 전까지 바꿀 수 있습니다.</p>

    <p>보통 몇가지 안정성 형식을 고려합니다:</p>
    <terms>
      <item>
        <title>불안정</title>
        <p>API를 바꾸거나 나중에 제거할 수 있습니다.</p>
      </item>
      <item>
        <title>하위 호환성</title>
        <p>수정한 API에서도 수정하지 않은 API에서 컴파일한 코드를 실행할 수 있을 경우(예: 함수는 제거할 수 없음)에만 바꿉니다.</p>
      </item>
      <item>
        <title>상위 호환성</title>
        <p>수정하지 않은 API에서도 수정한 API에서 컴파일한 코드를 실행할 수 있을 경우(예: 함수를 추가할 수 없음)에만 바꿉니다.</p>
      </item>
      <item>
        <title>완전 안정성</title>
        <p>API를 어떤식으로도 바꿀 수 없으며 구현 기능 바꾸기에 한정합니다.</p>
      </item>
    </terms>

    <p>일반적으로, API가 ‘안정적’이다 라고 한다면, 하위 호환성을 지닌 채로 프로젝트를 커밋합니다. 극히 일부 프로젝트의 경우 전체적인 안정성을 지닌 채로 커밋하는데 대부분의 전반적인 프로젝트를 앞으로 더 개발하지 못하게 하기 때문입니다.</p>
  </section>

  <section id="versioning">
    <title>버전 부여</title>

    <p>API 안정성은 프로젝트 버전 부여와 밀접한 연관성이 있습니다. 여기서 말하는 버전 부여는 패키지 버전 부여와 libtool 버전 부여를 둘 다 지칭합니다. libtool 버전 부여는 ABI 안정성을 추적하려는 목적으로 존재하며, 자세한 내용은 <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link> 또는 <link xref="versioning"/>에서 설명합니다.</p>

    <p>패키지 버전 부여(<em>major.minor.micro</em>)는 API 안정성과 밀접하게 연결됩니다. 보통 주 버전은 하위 비호환 변경 사항(함수 이름을 바꾸었다거나, 매개변수를 바꾸었다거나, 함수를 제거했을 경우)이 있을 경우 증가합니다. 부 버전은 상위 비호환 변경 사항(새 공개용 API 추가)이 있을 때 증가합니다. 세부 버전은 API를 수정하지 않는 선에서 코드가 바뀌었을 때 증가합니다. 자세한 내용은 <link xref="versioning"/> 링크를 참고하십시오.</p>

    <p>API 버전 부여는 D-Bus API와 GSettings 스키마(를 바꿀 것 같다면)에게 C API 만큼 중요합니다. 자세한 내용은 <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">D-Bus API 버전 부여 참고 문서</link>를 참고하십시오.</p>

    <p>GIR API는 C API로 만들기 때문에 GIR API의 안정성은 C API 안정성을 보통 따릅니다. 한가지 복잡한 점이 있다면 GIR API의 안정성은 GIR을 만들 때 사용하는 gobject-introspection의 버전을 따른다는 점인데, 최근 버전은 상당 부분이 바뀌지 않았기에 주된 고려 요소가 아닙니다.</p>
  </section>

  <section id="external-links">
    <title>외부 링크</title>

    <p>API 안정성을 주제로 다루는 글은 다음과 같습니다:</p>
    <list>
      <item><p><link href="http://en.wikipedia.org/wiki/Application_programming_interface">위키피디아의 API 페이지</link></p></item>
      <item><p><link href="http://en.wikipedia.org/wiki/Application_binary_interface">위키피디아의 ABI 페이지</link></p></item>
      <item><p><link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">D-Bus API 버전 부여 참고 문서</link></p></item>
    </list>
  </section>
</page>