diff --git a/templates/contribute/how-to-contribute.md b/templates/contribute/how-to-contribute.md index 98a407eca..2ae27f4fd 100644 --- a/templates/contribute/how-to-contribute.md +++ b/templates/contribute/how-to-contribute.md @@ -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. + In these situations, the change must be mentioned in the PR description, and a mitigation or fix provided there also. + * 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 diff --git a/templates/contribute/style.md b/templates/contribute/style.md index 4d7dc29a0..6a24d0f80 100644 --- a/templates/contribute/style.md +++ b/templates/contribute/style.md @@ -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.