[GH-ISSUE #971] How am I supposed to define the public API in end-user apps? #1466

New Issue

GiteaMirror · 2026-04-16T10:52:39-05:00

GiteaMirror commented

2026-04-16 10:52:39 -05:00

Originally created by @Secret-chest on GitHub (Sep 4, 2023).
Original GitHub issue: https://github.com/semver/semver/issues/971

Originally created by @Secret-chest on GitHub (Sep 4, 2023). Original GitHub issue: https://github.com/semver/semver/issues/971

GiteaMirror closed this issue

2026-04-16 10:52:39 -05:00

GiteaMirror commented

2026-04-16 10:52:40 -05:00

@jwdonahue commented on GitHub (Sep 5, 2023):

How am I supposed to define the public API in end-user apps?

Carefully.

I think your question might be a little too open ended. Ask yourself what features of your application are, or can be made stable? Too much depends on platform details for anybody to answer this question with any precision. I tend to consider the automatable test points in the UI as part of the interface (essentially all I/O). In Windows and other event driven GUI's you can often intercept and inject messages to specific components, determine their on screen location and other state, and determine adherence to UX specifications and standards at run-time. Those can be implicitly or explicitly considered part of your versionable interface.

There are some who would argue that every observable behavior is part of your interface, but this is extremely difficult to maintain when your application may run on a wide variety of devices, particularly when display attributes are end user controlled. In most cases, you should not attempt to claim every pixel as your versioned interface. So that leaves you with identifiable objects and their machine/OS interfaces. You might verify that there is a file menu on the menu bar or a folder widget on a tool bar. These things usually have discoverable Id's that can be used at run-time to drive them with test automation, or even manual test scripts.

Semantic versioning is all about communicating risks to your customers. You can definitely consider your product acceptance testers among your interface customers and consider how changes to your app will impact those testers. Depending on your application, you may have end users that rely on scriptable features. You should take into account how your application is intended to be used and consider that no matter your intent, customers will find other ways to use it. So, defining a versionable API for an end user APP requires that you make certain commitments and you should definitely consider exactly how committed you are willing to be.

Generally, inputs and outputs will be considered by customers as part of your interface. Does the app take command line arguments or a config file? What are the formats of those inputs and outputs?

@jwdonahue commented on GitHub (Sep 5, 2023): > How am I supposed to define the public API in end-user apps? Carefully. I think your question might be a little too open ended. Ask yourself what features of your application are, or can be made stable? Too much depends on platform details for anybody to answer this question with any precision. I tend to consider the automatable test points in the UI as part of the interface (essentially all I/O). In Windows and other event driven GUI's you can often intercept and inject messages to specific components, determine their on screen location and other state, and determine adherence to UX specifications and standards at run-time. Those can be implicitly or explicitly considered part of your versionable interface. There are some who would argue that every observable behavior is part of your interface, but this is extremely difficult to maintain when your application may run on a wide variety of devices, particularly when display attributes are end user controlled. In most cases, you should not attempt to claim every pixel as your versioned interface. So that leaves you with identifiable objects and their machine/OS interfaces. You might verify that there is a file menu on the menu bar or a folder widget on a tool bar. These things usually have discoverable Id's that can be used at run-time to drive them with test automation, or even manual test scripts. Semantic versioning is all about communicating risks to your customers. You can definitely consider your product acceptance testers among your interface customers and consider how changes to your app will impact those testers. Depending on your application, you may have end users that rely on scriptable features. You should take into account how your application is intended to be used and consider that no matter your intent, customers will find other ways to use it. So, defining a versionable API for an end user APP requires that you make certain commitments and you should definitely consider exactly how committed you are willing to be. Generally, inputs and outputs will be considered by customers as part of your interface. Does the app take command line arguments or a config file? What are the formats of those inputs and outputs?

GiteaMirror commented

2026-04-16 10:52:40 -05:00

@steveklabnik commented on GitHub (Sep 11, 2023):

Semver is not really useful for "end-user apps," it is more useful for libraries that people use as dependencies for their projects.

At the end of the day, it is 100% up to the person writing the software to decide what the API consists of, and what it does not.

@steveklabnik commented on GitHub (Sep 11, 2023): Semver is not really useful for "end-user apps," it is more useful for libraries that people use as dependencies for their projects. At the end of the day, it is 100% up to the person writing the software to decide what the API consists of, and what it does not.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#1466