Better documentation for "public API" requirement #499

New Issue

GiteaMirror · 2026-02-17T12:10:25-06:00

GiteaMirror commented

2026-02-17 12:10:25 -06:00

Originally created by @sfsinger19103 on GitHub (Aug 25, 2021).

Related to #666.

I'm a newbie to publishing software, trying to do it responsibly. I'm following the recommendations in the CII Best Practices. One of these recommendations is to use Semantic Versioning. I would like to do that!

Reading the documentation, though, I don't know exactly what I need to do to "declare a public API." It would be great if the specification either defined the term or had a pointer to a definition or, even better, some new-user-friendly documentation.

Here's the code repository btw.

Originally created by @sfsinger19103 on GitHub (Aug 25, 2021). Related to #666. I'm a newbie to publishing software, trying to do it responsibly. I'm following the recommendations in the [CII Best Practices](https://bestpractices.coreinfrastructure.org/en/projects/4078#changecontrol). One of these recommendations is to use Semantic Versioning. I would like to do that! Reading the documentation, though, I don't know exactly what I need to do to "declare a public API." It would be great if the [specification](https://semver.org) either defined the term or had a pointer to a definition or, even better, some new-user-friendly documentation. [Here's the code repository btw.](https://github.com/ElectionDataAnalysis/electiondata)

GiteaMirror closed this issue

2026-02-17 12:10:25 -06:00

GiteaMirror commented

2026-02-17 12:10:26 -06:00

@ljharb commented on GitHub (Aug 25, 2021):

Write prose documentation; add test coverage for it; and assume that anything anyone CAN do is something they'll try to treat as part of your API.

@ljharb commented on GitHub (Aug 25, 2021): Write prose documentation; add test coverage for it; and assume that anything anyone CAN do is something they'll try to treat as part of your API.

GiteaMirror commented

2026-02-17 12:10:26 -06:00

@sfsinger19103 commented on GitHub (Aug 25, 2021):

Thanks @ljharb. I still don't know what you're referring to when you say "your API". Is "my API" this page?

@sfsinger19103 commented on GitHub (Aug 25, 2021): Thanks @ljharb. I still don't know what you're referring to when you say "your API". Is "my API" [this page](https://github.com/ElectionDataAnalysis/electiondata/releases/tag/v1.0.0)?

GiteaMirror commented

2026-02-17 12:10:27 -06:00

@ljharb commented on GitHub (Aug 25, 2021):

Your API is "any way that your users interact with your project". If your project is a function, then the API is "how many arguments it takes, what kind of thing they are, and what kind of thing it returns" along with, of course, the semantics therein.

For example, https://github.com/ElectionDataAnalysis/electiondata/blob/main/docs/User_Guide.md#determining-a-munger describes params, their required format, what's optional, etc - that's all part of your API.

@ljharb commented on GitHub (Aug 25, 2021): Your API is "any way that your users interact with your project". If your project is a function, then the API is "how many arguments it takes, what kind of thing they are, and what kind of thing it returns" along with, of course, the semantics therein. For example, https://github.com/ElectionDataAnalysis/electiondata/blob/main/docs/User_Guide.md#determining-a-munger describes params, their required format, what's optional, etc - that's all part of your API.

GiteaMirror commented

2026-02-17 12:10:28 -06:00

@sfsinger19103 commented on GitHub (Aug 25, 2021):

Ok, so if I understand correctly, pointing to my reasonable documentation from the README.md of my GitHub repository counts as "declaring a public API."

@sfsinger19103 commented on GitHub (Aug 25, 2021): Ok, so if I understand correctly, pointing to my reasonable documentation from the README.md of my GitHub repository counts as "declaring a public API."

GiteaMirror commented

2026-02-17 12:10:28 -06:00

@ljharb commented on GitHub (Aug 25, 2021):

Seems like it to me. Personally I’d say that anything consumers are capable of doing counts as declaring it, but opinions differ :-)

@ljharb commented on GitHub (Aug 25, 2021): Seems like it to me. Personally I’d say that anything consumers are capable of doing counts as declaring it, but opinions differ :-)

GiteaMirror referenced this issue

2026-02-17 12:19:30 -06:00

[PR #499] [MERGED] convert original authorship to past tense #812

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#499