Skip to content

Guidance on breaking changes #912

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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
b-mehta wants to merge 2 commits into
base: lean4
Choose a base branch
from
Open

Guidance on breaking changes #912

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e98c0fa
Guidance on breaking changes
b-mehta Sep 9, 2026
d14a4b5
Update renaming and deprecation guidelines
b-mehta Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions templates/contribute/how-to-contribute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,10 @@ Once you're happy with your local changes, it's time to make a pull request to t
This helps you get feedback as you go along, and it is much easier to review.
This is especially important for new contributors as it prevents wasted effort.

* Avoid making *breaking* changes, i.e. PRs that make downstream code go from _working_ to _giving an error_.
However, this kind of change is sometimes necessary for the growth of mathlib, but should be carefully considered.

@grunweg grunweg Sep 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I'm not sure what exactly this sentence is contrasting. To me, the sentence reads fine without it.

Suggested change
However, this kind of change is sometimes necessary for the growth of mathlib, but should be carefully considered.
This kind of change is sometimes necessary for the growth of mathlib, but should be carefully considered.

@b-mehta b-mehta Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The intended message here is "You should avoid doing this unless you really have to, but sometimes you truly do have to". I'm happy with alternate wording which conveys this!

In these situations, the change must be mentioned in the PR description, and a mitigation or fix provided there also.

@grunweg grunweg Sep 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

To me, it's not 100% clear what this means. Do you have an example in mind? (Do you think we have been following this, or would this also be a proposed new policy?)

@b-mehta b-mehta Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I think this is followed in general, but not consistently. For example:


* The title and description of the PR should follow our [commit conventions](commit.html).

* If you are moving or deleting declarations, please include these lines at the bottom of the commit message
Expand Down
2 changes: 2 additions & 0 deletions templates/contribute/style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -849,6 +849,8 @@ also properly tagged with `to_additive`, like so:

We allow, but discourage, contributors from simultaneously renaming declarations X to Y and W to X.
In this case, no deprecation attribute is required for X, but it is for W.
Similarly, we discourage contributors from simultaneously renaming declarations from X to Y and "recycling" the name X for a new lemma.
In both of these situations, the rename *must* be mentioned explicitly in the PR description, together with its motivation.

Named instances do not require deprecations. Deprecated declarations can be deleted after 6 months.

Expand Down
Loading