📝 Update documentation regarding formatting files

Co-authored-by: Daniel McCloy <[email protected]>

Author: trallard

.git-blame-ignore-revs

@@ -2,8 +2,7 @@
 # commit hash here, so git blame can ignore the change.
 #
 # For more details, see:
-# https://git-scm.com/docs/git-config#Documentation/git-config.txt-blameignoreRevsFile
-# https://github.com/pydata/pydata-sphinx-theme/pull/713
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/community/topics/attribution.html
 #
 90550b66ace16a370caa446e54698b126fda740b # initial black-format
 236d4c6d1f10f5da064d929e9eb594daecf23551 # apply black 20.8b1 format

docs/community/topics/attribution.md

@@ -1,8 +1,27 @@
 # Ignore formatting commits with `git blame`
 
-When making commits that are strictly formatting/style changes (e.g., after running a new version of black or running pyupgrade after dropping an old Python version), add the commit hash to `.git-blame-ignore-revs`, so `git blame` can ignore the change.
+Please follow these steps to avoid obscuring files history when making commits that are
+strictly formatting/style changes (e.g., after running a new version of black or running
+pyupgrade after dropping an old Python version).
+
+1. Create a new branch.
+2. Make any linting and formatting rules needed; either in the `pre-commit.config.yaml`
+   or in the `pyproject.toml` file.
+3. Commit your changes with the `--no-verify` flag to skip the pre-commit hooks.
+4. Run the pre-commit hooks manually with `tox run -e lint` or `pre-commit run --all-files`.
+5. Commit the linting and formatting changes.
+6. Open a PR with these changes.
+
+   ```{important}
+   This PR **must** be rebased-merged -- instead of the default squash-merge we
+   currently follow -- so a repository admin needs to enable this setting in the
+   repository temporarily.
+
+   ```
+
+7. Open a new PR adding the commit hashes of the formatting commits to the `.git-blame-ignore-revs` file.
 
 For more details, see:
 
-- https://git-scm.com/docs/git-config#Documentation/git-config.txt-blameignoreRevsFile
-- https://github.com/pydata/pydata-sphinx-theme/pull/713
+- <https://git-scm.com/docs/git-config#Documentation/git-config.txt-blameignoreRevsFile>
+- <https://github.com/pydata/pydata-sphinx-theme/pull/713>