From 2e2a95743080bacb70681404e97ef66ff47a0f69 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 28 Nov 2024 11:01:43 +0000 Subject: [PATCH 1/2] :memo: Update documentation regarding formatting files 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 1bfbc3c70e..3f02aaa3f1 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 bfbae9616a..a5f3204afe 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 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 +- +- From 3f303570fa50c963d41649b882915dce9af62407 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Thu, 28 Nov 2024 16:45:35 +0000 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Daniel McCloy --- docs/community/topics/attribution.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/community/topics/attribution.md b/docs/community/topics/attribution.md index a5f3204afe..619fb7f410 100644 --- a/docs/community/topics/attribution.md +++ b/docs/community/topics/attribution.md @@ -1,6 +1,6 @@ # Ignore formatting commits with `git blame` -Please follow these steps to avoid obscuring files history when making commits that are +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). @@ -13,7 +13,7 @@ pyupgrade after dropping an old Python version). 6. Open a PR with these changes. ```{important} - This PR **must** be rebased-merged -- instead of the default squash-merge we + 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.