Semver tagging commits

[capsulecorplab]

Semver tagged commits would be useful for knowing when there's been a breaking change, feature addition, and/or bug fix in the Docsy theme, perhaps as part of a release cycle. Any thoughts?

[LisaFC]

@emckean is looking into this....

[emckean]

Docsy is looking into using Semantic Versioning (semver)!

So the basic idea of semver (from the spec) is that

Given a version number MAJOR.MINOR.PATCH, you increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
PATCH version when you make backwards compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Docsy semver proposal

For Docsy (and docsy-example) the idea would be that we'd increment:

• major version:

  • updates to Hugo or Bootstrap (or any other dependency) that are themselves major version changes (for example, updating to Bootstrap 5)
  • introduces changes (including to .toml files or features) that are not backwards-compatible (example: when the HUGO_ENV=production behavior changed)

• minor version:

  • any changes that are backwards compatible but bigger than bugfixes (for example, adding new language support, adding support for other search options)
  • updates to dependencies that are minor versions

• patch:

  • backwards-compatible bugfixes
  • updates to dependencies that are patch versions

We'd also want to use alpha and beta to identify branches that are in development and/or ready for testing before release.

when would Docsy start using semver?

The goal would be to build consensus via discussion here and begin with a version 1.0.0 early in 2022.

how/who would decide what's major/minor/patch?

We're working on putting together a project steering committee that would have the final say (ping me if you're interested in being on the committee!), but we'd also ask people making pull requests to indicate whether their PR is a backwards-compatible new feature, an incompatible change or feature, or a bugfix.

what else is needed?

As part of adding semver, we should also create a CHANGELOG process and create/implement some tooling to make releasing versions easier.

want to help?

Comment in this discussion with your questions or recommendations! If you have suggestions about how to make this easier (tooling, release process, etc) please also open an issue with your recommendation and tag it semver.

[deining]

I really like the idea of Semver tagged commits. This also would play nicely with hugo modules, as proposed in #801.
With hugo modules in place, switching back and forth between releases could be easily done via a one-liner:

hugo mod get -u github.com/google/[email protected]

[chalin]

Thanks for the proposal @emckean!

While I'm an advocate for the adoption of semver, I'd like to point out the following. Among of the most significant consequences of adopting semver is the need for (IMHO):

• A release plan -- e.g., say, a new major release every X months
• A support plan -- e.g., only the latest Y releases are officially supported
• Separate branches for each major release
• A back-porting plan to ensure that bugs fixed in one major release get propagated to other relevant releases
  • It might be necessary to name official (possibly elected and limited-term) maintainers for each major release

All of that is a lot of work for a project that is already ... understaffed! Hopefully, community involvement will pick up. Looking forward to the first Steering Committee meeting.

[emckean]

I agree with all those caveats :)

[chalin]

I'd like to suggest that while we have our training wheels on, we do like Hugo -- that is, adopt the following semver-ish numbering scheme:

0.MAJOR.MINOR

and if necessary, +PATCH (or +BUILD) at the end though I suspect that we won't need it. Thoughts @emckean et al?

[emckean]

SGTM!

…

On Fri, Jan 14, 2022 at 10:04 AM Patrice Chalin ***@***.***> wrote: I'd like to suggest that while we have our training wheels on, we do like Hugo -- that is, adopt the following semver-ish numbering scheme: 0.MAJOR.MINOR and if necessary, +PATCH (or +BUILD) at the end though I suspect that we won't need it. Thoughts @emckean <https://github.com/emckean> et al? — Reply to this email directly, view it on GitHub <#619 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABXBGNLI7ZS2YPVJZPFAQ3UWBQTRANCNFSM475Y5EOQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Erin McKean | Docs Advocacy Program Manager, Open Source Programs Office | ***@***.*** | she/her