From 0ca99135b84e2a623382cf67b70d1e4bd96b2152 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Dec 2024 20:33:54 +0000 Subject: [PATCH] DOC - Update documentation regarding formatting files (#2057) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .git-blame-ignore-revs | 3 +-- docs/community/topics/attribution.md | 25 ++++++++++++++++++++++--- 2 files changed, 23 insertions(+), 5 deletions(-) diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs index 1bfbc3c70..3f02aaa3f 100644 --- 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 index bfbae9616..619fb7f41 100644 --- 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 +- +-