semantic versioning - semver - ¿Qué significa "api pública" en Versiones semánticas?

versioning git

Question

Estoy aprendiendo sobre cómo asignar e incrementar los números de versión con la regla llamada "Versiones semánticas" de http://semver.org/ .

Entre todas sus reglas, la primera decía:

El software que utiliza la versión semántica DEBE declarar una API pública. Esta API podría declararse en el código mismo o existir estrictamente en la documentación. Sin embargo, se hace, debe ser preciso y completo "

Estoy confundido acerca de "API pública". ¿A que se refiere?

Answer 1

Habiendo leído la especificación un par de veces,

1. El software que utiliza la versión semántica DEBE declarar una API pública. Esta API podría declararse en el código mismo o existir estrictamente en la documentación. Sin embargo, se hace, debe ser preciso y completo.

Me pregunto si todo lo que significa es que los consumidores de su software deben poder establecer la versión "semántica" precisa que están utilizando.

Por ejemplo, podría producir un script simple donde la versión semántica está en el nombre del script:

DoStuff_1.0.0.ps1

Es público y preciso. No solo en mi cabeza :)

Answer 2

La API pública se refiere al "punto de acceso" que el mundo externo (usuarios, otros programas y / o programadores, etc.) tiene para su software.

Por ejemplo, si está desarrollando una biblioteca, la API pública es el conjunto de todos los métodos de invocación que se pueden realizar en su biblioteca.

Se entiende que, a menos que cambie una versión importante, su API será compatible con versiones anteriores, es decir, todas las llamadas que eran válidas en una versión serán válidas en una versión posterior. Puedes leer en el punto 9 de esas reglas:

La versión principal X (Xyz | X> 0) DEBE incrementarse si se introducen cambios incompatibles hacia atrás en la API pública.

Answer 3

Requiere una API pública para aplicar de manera efectiva su patrón de versiones.

Por ejemplo:

Las correcciones de errores que no afectan la API incrementan la versión del parche

Las adiciones / cambios de API compatibles con versiones anteriores incrementan la versión secundaria, y ...

Los cambios de API incompatibles hacia atrás incrementan la versión principal.

Lo que representa su API es subjetivo, ya que incluso se indican en el documento SemVer:

Esto puede consistir en documentación o ser ejecutado por el propio código.