Skip to content

Document and enforce a consistent release-notes date format #423

Description

@miharp

Summary

Release-notes dates drift between Month D, YYYY and ISO 8601, because the format is not written down anywhere and nothing in CI checks it.

Background

#419 normalized three dates in docs/_openvox-server_8x/release_notes.markdown from Released 2026-07-22. to Released July 22, 2026..

Before that PR, the repo stood at 19 spelled-out dates against 3 ISO ones, and the openvox-server release notes page was internally inconsistent, carrying both formats on the same page. The ISO dates were not a single bad import. They arrived on at least two separate occasions three months apart: fa735cddf (2026-05-04, the 8.13.0 date) and again with the 8.15.x notes in July.

So this will recur the next time someone adds a release stanza.

Why the spelled-out form

CONTRIBUTING.md says to follow the Google developer documentation style guide, which calls for January 1, 2016 and specifically discourages all-numeric dates as ambiguous across locales. That is also what 19 of the 22 existing dates already use.

The gap is that CONTRIBUTING.md never says this explicitly. It only defers to Google's guide in general, which is easy to miss when you are pattern-matching off a nearby release stanza that happens to use the other format.

Proposed fix

Two options, not mutually exclusive:

1. Document it. Add a line under ### Grammar and spelling in CONTRIBUTING.md:

  • Dates: use Month D, YYYY (May 4, 2026); avoid all-numeric formats, which are ambiguous across locales

2. Enforce it. A check would catch this at PR time rather than at review time. The pattern is narrow enough to match reliably:

^Released [0-9]{4}-[0-9]{2}-[0-9]{2}

CI already runs both markdownlint-cli2 and rake, so this could live in either:

  • a markdownlint custom rule (customRules is not currently configured in .markdownlint-cli2.yaml, so this would be the first)
  • or a small rake task alongside the existing test:links

Option 1 alone is cheap and probably worth doing regardless. Option 2 is what actually prevents recurrence.

Notes

  • Follow-up to use consistent format for release dates #419, which fixed the existing instances. Not a blocker for that PR.
  • Scope is release-notes dates specifically. Worth deciding whether the rule should apply to dates in prose elsewhere in docs/ too.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions