Implications of "Docs as Code" #370

New Issue

GiteaMirror · 2026-02-17T11:57:00-06:00

GiteaMirror commented

2026-02-17 11:57:00 -06:00

Originally created by @ccallawa on GitHub (Feb 22, 2019).

Given that more developers are moving to the model of very tightly coupling documentation with code releases, you could add something about the implications, e.g.:

Bugfix releases (patch version, x.y.v -> x.y.w) should contain no new documentation that is not a clarification of existing documentation, on the principle that fixing bugs doesn't add new functionality, but rather makes the code work as the documentation already described it. Clarifications should only address why the documentation wasn't specific enough in the first place due to mistaken assumptions.
Every feature change in a minor version update (x.v.z -> x.w.z) must be accompanied by the documentation for each change marked as a new feature in the changelog

Originally created by @ccallawa on GitHub (Feb 22, 2019). Given that more developers are moving to the model of very tightly coupling documentation with code releases, you could add something about the implications, e.g.: - Bugfix releases (patch version, x.y.v -> x.y.w) should contain no new documentation that is not a clarification of existing documentation, on the principle that fixing bugs doesn't add new functionality, but rather makes the code work as the documentation already described it. Clarifications should only address why the documentation wasn't specific enough in the first place due to mistaken assumptions. - Every feature change in a minor version update (x.v.z -> x.w.z) must be accompanied by the documentation for each change marked as a new feature in the changelog

GiteaMirror added the waiting for PR label 2026-02-17 11:57:00 -06:00

GiteaMirror commented

2026-02-17 11:57:02 -06:00

@FichteFoll commented on GitHub (Feb 22, 2019):

Given that the "Public API" is usually defined by documentation, this seems to be covered by semver already.
Imo the Public API part of the spec should be clarified instead.

@FichteFoll commented on GitHub (Feb 22, 2019): Given that the "Public API" is usually *defined* by documentation, this seems to be covered by semver already. Imo the Public API part of the spec should be clarified instead.

GiteaMirror commented

2026-02-17 11:57:04 -06:00

@jwdonahue commented on GitHub (Jan 17, 2020):

@ccallawa, unless you intend to issue a PR or have further questions, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Jan 17, 2020): @ccallawa, unless you intend to issue a PR or have further questions, please close this issue at your earliest possible convenience.

GiteaMirror referenced this issue

2026-04-16 10:24:24 -05:00

[GH-ISSUE #370] Handling new medium/major version #1143

GiteaMirror referenced this issue

2026-04-20 09:53:05 -05:00

[GH-ISSUE #370] Handling new medium/major version #2010

GiteaMirror referenced this issue

2026-04-25 17:09:46 -05:00

[GH-ISSUE #370] Handling new medium/major version #2992

GiteaMirror referenced this issue

2026-06-13 12:42:03 -05:00

[GH-ISSUE #370] Handling new medium/major version #4521