Skip to content

[docs] document use of EffVer #6905

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 21, 2025
Merged

[docs] document use of EffVer #6905

merged 5 commits into from
May 21, 2025

Conversation

jameslamb
Copy link
Collaborator

@jameslamb jameslamb commented Apr 29, 2025

For a long time now, this project has not been strictly following semantic versioning.

Look through https://github.com/microsoft/LightGBM/releases and you will find entries in the "Breaking" section for release v4.6.0, v4.5.0, v4.4.0, etc.

Without knowing it, for several years we've been following a scheme that my friend @jacobtomlinson calls Intended Effort Versioning ("EffVer"): https://jacobtomlinson.dev/effver/

In that scheme, you use a 3-part version where changes to each part answer the question "how much effort will it take for me to upgrade to this version?".

This PR proposes explicitly documenting that, so we have somewhere to point people who ask questions like "why did you only update the minor version component if this release contains breaking changes?".

Notes for Reviewers

Why put this in the Installation Guide?

I think this type of information is useful in the Installation Guide because it helps users to decide how to create dependency pins on LightGBM.

If we don't like this here, I think it should go in the development docs: https://lightgbm.readthedocs.io/en/latest/Development-Guide.html

I've added this branch (temporarily) to the readthedocs config

Builds: https://app.readthedocs.org/projects/lightgbm/builds/?version__slug=docs-effver

Copy link
Collaborator

@StrikerRUS StrikerRUS left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, I like this clarification about our version schema!


{major}.{minor}.{patch}.99

That ``.99`` is added to ensure that a version built from an unreleased commit is considered "newer"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe move paragraph about nightly builds here?

.. _nightly-builds:
You can download the artifacts of the latest successful build on master branch (nightly builds) here: |download artifacts|.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, good idea! Moved that in 0338d2c

If you wanted a slightly different placement, it's ok with me if you push directly to this branch.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perfect, thanks!

@StrikerRUS
Copy link
Collaborator

Seems that Azure builds are stuck again (see latest master commit)... 😕

@shiyu1994 Could you please check Azure Linux runner?

@jameslamb
Copy link
Collaborator Author

@shiyu1994 can you please help us here?

All of the Linux Azure DevOps jobs are getting stuck in queued, I guess because the runners are not available.

image

example build link: https://dev.azure.com/lightgbm-ci/lightgbm-ci/_build/results?buildId=17767&view=results

@StrikerRUS
Copy link
Collaborator

Kindly ping @shiyu1994

@StrikerRUS
Copy link
Collaborator

Merging is blocked
Waiting on 1 reapproval from someone other than the last pusher. Review from StrikerRUS is stale because it was submitted before the most recent code changes.

Hmmm, looks like someone rolled back this repo setting: #6872 (comment)

@shiyu1994 Could you please check?

@StrikerRUS StrikerRUS merged commit 17fda87 into master May 21, 2025
51 checks passed
@StrikerRUS StrikerRUS deleted the docs/effver branch May 21, 2025 08:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants