DOC - Update documentation regarding formatting files (#2057)

First, thanks @drammock, for helping with the lining issues 💜 Since we had some hiccups dealing with these PRs/items I decided to update our docs to include the suggested workflow (I added @drammock as a co-author since he helped figure out what this looked like) --------- Co-authored-by: Daniel McCloy <[email protected]>
pydata · Dec 2, 2024 · 0ca9913 · 0ca9913
1 parent a009a24
commit 0ca9913
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 5 deletions.
diff --git a/.git-blame-ignore-revs b/.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

diff --git a/docs/community/topics/attribution.md b/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 file 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 rebase-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>