[binutils-gdb] Add .pre-commit-config.yaml

[binutils-gdb] Add .pre-commit-config.yaml

[Simon Marchi]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=e8f6050cfb990452fcfc685bc9ccbae79113fa36

commit e8f6050cfb990452fcfc685bc9ccbae79113fa36
Author: Simon Marchi <simon.marchi@efficios.com>
Date:   Mon Mar 11 11:09:43 2024 -0400

    Add .pre-commit-config.yaml
    
    Add a pre-commit [1] config file, with a single hook to run black on the
    gdb directory whenever a Python file is modified.  We can always add
    more hooks if we find some that are useful.
    
    Using pre-commit to run hooks is opt-in, as in it's not mandatory at all
    for development, but it can be useful to run some checks that are easy
    to forget (like running black).  The hooks run locally on the
    developer's machine when doing `git commit` (although they can also be
    configured to run at other stages of the git workflow).
    
    Follow these instructions to install the hooks in your local development
    git repository:
    
     - Install pre-commit the way you prefer.  It can be using your OS
       package manager if it has a recent enough version, or using `pip
       install pre-commit`.
     - Go to the binutils-gdb repository and run `pre-commit install`.
    
    This installs a git hook at `.git/hooks/pre-commit`.
    
    Now, whenever you modify and try to commit a Python file, pre-commit
    will run black on it.  For instance, if I try to insert something
    misformatted, I get this when doing `git commit`:
    
        $ git commit
        black....................................................................Failed
        - hook id: black
        - files were modified by this hook
    
        reformatted gdb/python/lib/gdb/dap/breakpoint.py
    
        All done! ✨ 🍰 ✨
        1 file reformatted.
    
    At this point, black has already reformatted the files in place, so the
    changes that fix the formatting are ready to add and commit.  black is
    only ran on files modified in the commit.
    
    The hook defines a black version, which is downloaded at `pre-commit
    install` time.  pre-commit manages its own env at
    `$HOME/.cache/pre-commit/<some-hash>`, so it won't use the version of
    black you have installed already.  This may help ensure that
    contributors use the right black version.
    
    The procedure when there is a new version of black (or a new version of
    any hook we might be using in the future) is:
    
     - Modify .pre-commit-config.yaml to change the version number, push to
       the upstream repo.
     - Have contributors run `pre-commit autoupdate` to make their local
       pre-commit installation update the hooks.
    
    It is possible to have pre-commit skip some hooks if needed [2].
    
    I will add these instructions to the wiki if this patch gets merged, so
    they are easy to find.  We could perhaps think of having a
    gdb/CONTRIBUTING document of some sort checked in the repo with that
    kind of information.
    
    I have not used pre-commit in a real project before, but have heard good
    things from it.  If we want to give it a try before pushing it to the
    repo, some volunteers can copy the .pre-commit-config.yaml file locally
    and try it for some time.  However, pushing the file upstream is not
    going to impact anybody who doesn't care about it, so I'd say it's
    relatively low-risk to push it right now.
    
    [1] https://pre-commit.com
    [2] https://pre-commit.com/#temporarily-disabling-hooks
    
    Change-Id: Id00cda882f5140914a670c87e574fa7f2f972099
    Acked-By: Tom Tromey <tromey@adacore.com>
    Acked-By: Guinevere Larsen <blarsen@redhat.com>
    Acked-By: Andrew Burgess <aburgess@redhat.com>

Diff:
---
 .pre-commit-config.yaml | 8 ++++++++
 ChangeLog               | 4 ++++
 2 files changed, 12 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 00000000000..b8d1ef7dc74
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,8 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 24.2.0
+    hooks:
+      - id: black
+        files: 'gdb/.*'
diff --git a/ChangeLog b/ChangeLog
index 91b9f774ada..e1b17767d47 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2024-03-20  Simon Marchi  <simon.marchi@efficios.com>
+
+	* .pre-commit-config.yaml: New.
+
 2024-03-14  Simon Marchi  <simon.marchi@efficios.com>
 
 	* Makefile.def: Add configure-gdbserver and all-gdbserver