DOC Add section on resolving conflicts in lock files to developer guide (#29882)

StefanieSenger · jeremiedbb · commit cce5062a5fb2 · 2024-12-06T22:23:50.000+01:00
diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst
@@ -562,12 +562,15 @@ Commit Message Marker  Action Taken by CI
 Note that, by default, the documentation is built but only the examples
 that are directly modified by the pull request are executed.
 
-Lock files
-^^^^^^^^^^
+.. _build_lock_files:
+
+Build lock files
+^^^^^^^^^^^^^^^^
 
 CIs use lock files to build environments with specific versions of dependencies. When a
 PR needs to modify the dependencies or their versions, the lock files should be updated
-accordingly. This can be done by commenting in the PR:
+accordingly. This can be done by adding the following comment directly in the GitHub
+Pull Request (PR) discussion:
 
 .. code-block:: text
 
@@ -592,6 +595,36 @@ update documentation-related lock files and add the `[doc build]` marker to the
 
   @scikit-learn-bot update lock-files --select-build doc --commit-marker "[doc build]"
 
+Resolve conflicts in lock files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here is a bash snippet that helps resolving conflicts in environment and lock files:
+
+.. prompt:: bash
+
+  # pull latest upstream/main
+  git pull upstream main --no-rebase
+  # resolve conflicts - keeping the upstream/main version for specific files
+  git checkout --theirs  build_tools/*/*.lock build_tools/*/*environment.yml \
+      build_tools/*/*lock.txt build_tools/*/*requirements.txt
+  git add build_tools/*/*.lock build_tools/*/*environment.yml \
+      build_tools/*/*lock.txt build_tools/*/*requirements.txt
+  git merge --continue
+
+This will merge `upstream/main` into our branch, automatically prioritising the
+`upstream/main` for conflicting environment and lock files (this is good enough, because
+we will re-generate the lock files afterwards).
+
+Note that this only fixes conflicts in environment and lock files and you might have
+other conflicts to resolve.
+
+Finally, we have to re-generate the environment and lock files for the CIs, as described
+in :ref:`Build lock files <build_lock_files>`, or by running:
+
+.. prompt:: bash
+
+  python build_tools/update_environments_and_lock_files.py
+
 .. _stalled_pull_request:
 
 Stalled pull requests
diff --git a/doc/developers/tips.rst b/doc/developers/tips.rst
@@ -218,12 +218,6 @@ PR-WIP: Regression test needed
 
     Please add a [non-regression test](https://en.wikipedia.org/wiki/Non-regression_testing) that would fail at main but pass in this PR.
 
-PR-WIP: PEP8
-
-::
-
-    You have some [PEP8](https://www.python.org/dev/peps/pep-0008/) violations, whose details you can see in the Circle CI `lint` job. It might be worth configuring your code editor to check for such errors on the fly, so you can catch them before committing.
-
 PR-MRG: Patience
 
 ::
