Sync GitHub linting with Meta's internal pyfmt configuration (#154)

Summary:
This change synchronizes the GitHub Actions linting workflow with Meta's internal pyfmt configuration to ensure consistent code formatting between internal and external development environments.

Previously, the GitHub workflow used `black` directly for formatting checks, which caused discrepancies with Meta's internal linting that uses `ruff-api` (via ufmt). This led to situations where code would pass Meta's `pyfmt` checks but fail GitHub CI, or vice versa.

This diff adds:
1. **Configuration files** matching Meta's internal setup:
   - `.flake8` - Flake8 configuration with Black-compatible ignore rules
   - `pyproject.toml` - ufmt configuration using ruff-api formatter and usort
   - `requirements-fmt.txt` - Pinned versions from Meta's internal tools/lint/pyfmt/reqs/requirements-fmt.txt
   - `.pre-commit-config.yaml` - Pre-commit hooks for ufmt and flake8

2. **GitHub workflow updates**:
   - Replaced `black --check .` with `ufmt check .`
   - Added all required dependencies (black==24.4.2, ruff-api==0.1.0, ufmt==2.8.0, usort==1.0.8.post1)
   - Fixed flake8 invocation to use explicit path

3. **Documentation updates**:
   - Updated CONTRIBUTING.md with comprehensive linting and formatting instructions
   - Documented the new workflow for contributors
   - Explained configuration files and their purposes

The versions are pinned to exactly match Meta's internal setup, ensuring 100% consistency between environments.

Pull Request resolved: #154

Reviewed By: atavory

Differential Revision: D87183125

Pulled By: talgalili

fbshipit-source-id: 1445a9af1f093cb9d103d914c5eedb65fce569a8

Author: talgalili

.flake8

@@ -4,3 +4,19 @@
 # W503: Line break before binary operator
 # E203: Whitespace before ':'
 ignore = E501, W503, E203
+
+# Match Black's default line length
+max-line-length = 88
+
+# Exclude common directories
+exclude =
+    .git,
+    __pycache__,
+    .venv,
+    venv,
+    build,
+    dist,
+    *.egg-info,
+    .github,
+    website/node_modules,
+    sphinx/_build

.github/workflows/build-and-test.yml

@@ -46,10 +46,13 @@ jobs:
         python-version: 3.9
     - name: Install dependencies
       run: |
-        pip install flake8
+        pip install flake8 black==24.4.2 ruff-api==0.1.0 ufmt==2.8.0 usort==1.0.8.post1
     - name: Flake8
       run: |
-        flake8
+        flake8 .
+    - name: ufmt (formatting check)
+      run: |
+        ufmt check .
 
   test-deploy-website:
     name: Test website build

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/omnilib/ufmt
+    rev: v2.8.0
+    hooks:
+      - id: ufmt
+        additional_dependencies:
+          - black==24.4.2
+          - ruff-api==0.1.0
+          - usort==1.0.8.post1
+          - stdlibs
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        additional_dependencies: []

CONTRIBUTING.md

@@ -30,10 +30,41 @@ outlined on that page and do not file a public issue.
 
 ### Coding Style
 * 4 spaces for indentation rather than tabs
-* 80 character line length
+* 88 character line length
 
-### Linting
-Run the linter via `flake8` (`pip install flake8`) from the root of the Ax repository. Note that we have a [custom flake8 configuration](https://github.com/facebookresearch/balance/blob/main/.flake8).
+### Linting and Code Formatting
+
+We use **ufmt** (µfmt) for code formatting and **flake8** for linting. This matches Meta's internal pyfmt tooling and ensures consistency between internal and external development.
+
+**Installation:**
+```bash
+pip install -r requirements-fmt.txt
+```
+
+**Running formatters and linters:**
+```bash
+# Check formatting (doesn't modify files)
+ufmt check .
+
+# Auto-format code
+ufmt format .
+
+# Run flake8 linter
+flake8 .
+```
+
+**Pre-commit hooks (optional but recommended):**
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+After installing pre-commit hooks, formatting and linting will run automatically on every commit.
+
+**Configuration files:**
+- `.flake8` - Custom flake8 configuration
+- `pyproject.toml` - Configuration for ufmt, black, and usort
+- `requirements-fmt.txt` - Pinned versions of formatting tools matching Meta's internal setup
 
 ### Static Type Checking
 We use [Pyre](https://pyre-check.org/) for static type checking and require code to be fully type annotated.

pyproject.toml

@@ -0,0 +1,10 @@
+[tool.ufmt]
+formatter = "ruff-api"
+sorter = "usort"
+
+[tool.black]
+line-length = 88
+target-version = ["py39", "py310", "py311", "py312", "py313"]
+
+[tool.usort]
+first_party_detection = false

requirements-fmt.txt

@@ -0,0 +1,8 @@
+# Generated from Meta's internal pyfmt requirements
+# Keep these versions in sync with Meta's internal
+# tools/lint/pyfmt/reqs/requirements-fmt.txt
+black==24.4.2
+ruff-api==0.1.0
+stdlibs==2024.1.28
+ufmt==2.8.0
+usort==1.0.8.post1