Add comprehensive testing instructions to docs

Co-authored-by: yebai <[email protected]>

Author: Copilot

CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing to Bijectors.jl
+
+Thank you for your interest in contributing to Bijectors.jl! This guide will help you set up your development environment and understand how to run tests locally.
+
+## Development Setup
+
+ 1. **Clone the repository**:
+    
+    ```bash
+    git clone https://github.com/TuringLang/Bijectors.jl.git
+    cd Bijectors.jl
+    ```
+
+ 2. **Install dependencies**:
+    
+    ```bash
+    julia --project=. -e "using Pkg; Pkg.instantiate()"
+    ```
+ 3. **Verify the package loads**:
+    
+    ```bash
+    julia --project=. -e "using Bijectors; println(\"Package loaded successfully\")"
+    ```
+
+## Running Tests
+
+### Reproducing CI Test Failures
+
+When CI tests fail, the output often shows incomplete reproduction instructions. Here are the correct commands to reproduce different CI scenarios locally:
+
+#### Interface Tests
+
+```bash
+julia --project=. -e "ENV[\"GROUP\"] = \"Interface\"; using Pkg; Pkg.test()"
+```
+
+#### AD Tests with Specific Backend
+
+Replace `BackendName` with the failing AD backend from the CI output:
+
+```bash
+# ForwardDiff
+julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"ForwardDiff\"; using Pkg; Pkg.test()"
+
+# ReverseDiff  
+julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"ReverseDiff\"; using Pkg; Pkg.test()"
+
+# Tracker
+julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"Tracker\"; using Pkg; Pkg.test()"
+
+# Enzyme (may fail on some systems - this is expected)
+julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"Enzyme\"; using Pkg; Pkg.test()"
+
+# Mooncake
+julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"Mooncake\"; using Pkg; Pkg.test()"
+```
+
+#### Full Test Suite
+
+```bash
+julia --project=. -e "using Pkg; Pkg.test()"
+```
+
+### CI Test Matrix
+
+Our CI runs tests with the following configurations:
+
+  - **Interface tests**: Core functionality tests (GROUP=Interface)
+  - **AD tests**: Automatic differentiation tests with multiple backends (GROUP=AD, AD={ForwardDiff,ReverseDiff,Tracker,Enzyme,Mooncake})
+
+### Important Notes
+
+ 1. **Always use `--project=.`**: This ensures Julia uses the correct project environment with the right dependencies.
+
+ 2. **Environment variables matter**: The `GROUP` and `AD` environment variables control which tests run, matching the CI configuration.
+ 3. **Enzyme tests may fail**: Due to system compatibility issues, Enzyme tests may fail on some machines. This is expected and not a blocker for development.
+ 4. **Test timing**:
+    
+      + Interface tests: ~7.5 minutes
+      + AD tests (single backend): ~1.5 minutes
+      + Full test suite: 20+ minutes
+
+## Code Formatting
+
+We use JuliaFormatter.jl for consistent code formatting:
+
+```bash
+# Install formatter (one-time setup)
+julia --project=. -e "using Pkg; Pkg.add(\"JuliaFormatter\")"
+
+# Format code
+julia --project=. -e "using JuliaFormatter; format(\".\")"
+```
+
+## Documentation
+
+To build documentation locally:
+
+```bash
+julia --project=docs -e "using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); include(\"docs/make.jl\")"
+```
+
+## Validation Checklist
+
+Before submitting a PR, please ensure:
+
+  - [ ] Package loads without errors: `julia --project=. -e "using Bijectors"`
+  - [ ] Interface tests pass: `julia --project=. -e "ENV[\"GROUP\"] = \"Interface\"; using Pkg; Pkg.test()"`
+  - [ ] Code is formatted: `julia --project=. -e "using JuliaFormatter; format(\".\")"`
+  - [ ] Basic functionality works (see test scenarios below)
+
+### Basic Test Scenarios
+
+You can manually verify basic functionality:
+
+```julia
+using Bijectors, Distributions
+
+# Test 1: Basic bijector for LogNormal  
+d = LogNormal()
+b = bijector(d)
+x = 1.0
+y = b(x)  # Should return 0.0
+
+# Test 2: Inverse transformation
+x_reconstructed = inverse(b)(y)  # Should return 1.0
+
+# Test 3: Log absolute determinant of Jacobian
+logjac = logabsdetjac(b, x)
+
+# Test 4: Combined transformation  
+z, logabsdet = with_logabsdet_jacobian(b, x)
+```
+
+## Getting Help
+
+If you need help:
+
+  - Join the #turing channel on [Julia Slack](https://julialang.org/slack/)
+  - Ask questions on [Julia Discourse](https://discourse.julialang.org)
+  - Open a GitHub issue for bugs or feature requests
+
+Thank you for contributing to Bijectors.jl!

README.md

@@ -12,6 +12,37 @@ This package is used heavily in the probabilistic programming language Turing.jl
 
 See the [documentation](https://turinglang.github.io/Bijectors.jl) for more.
 
+## Development
+
+### Running Tests Locally
+
+To reproduce CI test failures locally, use the following commands:
+
+```bash
+# Install dependencies
+julia --project=. -e "using Pkg; Pkg.instantiate()"
+
+# Interface tests (reproduces "Interface tests" CI workflow)
+julia --project=. -e "ENV[\"GROUP\"] = \"Interface\"; using Pkg; Pkg.test()"
+
+# AD tests with specific backend (reproduces "AD tests" CI workflow)
+# Replace "ReverseDiff" with the specific AD backend from the failing CI job
+julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"ReverseDiff\"; using Pkg; Pkg.test()"
+
+# Other AD backends available:
+# julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"ForwardDiff\"; using Pkg; Pkg.test()"
+# julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"Mooncake\"; using Pkg; Pkg.test()"
+# julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"Tracker\"; using Pkg; Pkg.test()"
+# julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"Enzyme\"; using Pkg; Pkg.test()"
+
+# Run all tests
+julia --project=. -e "using Pkg; Pkg.test()"
+```
+
+**Note**: When reproducing CI failures, ensure you use the correct environment variables (`GROUP` and `AD`) and always include `--project=.` in your Julia commands. These are required for the tests to run in the same configuration as CI.
+
+For more detailed development instructions, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Do you want to contribute?
 
 If you feel you have some relevant skills and are interested in contributing, please get in touch!

src/bijectors/named_bijector.jl

@@ -139,7 +139,7 @@ deps(b::NamedCoupling{<:Any,Deps}) where {Deps} = Deps
     return quote
         b = nc.f($([:(x.$d) for d in deps]...))
         x_target, logjac = with_logabsdet_jacobian(b, x.$target)
-        return merge(x, ($target=x_target,)), logjac
+        return merge(x, (($target)=x_target,)), logjac
     end
 end
 
@@ -149,6 +149,6 @@ end
     return quote
         ib = inverse(ni.orig.f($([:(x.$d) for d in deps]...)))
         x_target, logjac = with_logabsdet_jacobian(ib, x.$target)
-        return merge(x, ($target=x_target,)), logjac
+        return merge(x, (($target)=x_target,)), logjac
     end
 end

test/ad/enzyme.jl

@@ -6,8 +6,7 @@
     @testset "forward" begin
         # No batches
         @testset for RT in (Const, Duplicated, DuplicatedNoNeed),
-            Tx in (Const, Duplicated),
-            Ty in (Const, Duplicated),
+            Tx in (Const, Duplicated), Ty in (Const, Duplicated),
             Tz in (Const, Duplicated)
 
             # Rule not picked up by Enzyme on Julia 1.11?!
@@ -21,8 +20,7 @@
 
         # Batches
         @testset for RT in (Const, BatchDuplicated, BatchDuplicatedNoNeed),
-            Tx in (Const, BatchDuplicated),
-            Ty in (Const, BatchDuplicated),
+            Tx in (Const, BatchDuplicated), Ty in (Const, BatchDuplicated),
             Tz in (Const, BatchDuplicated)
 
             # Rule not picked up by Enzyme on Julia 1.11?!
@@ -37,8 +35,7 @@
     @testset "reverse" begin
         # No batches
         @testset for RT in (Const, Active),
-            Tx in (Const, Active),
-            Ty in (Const, Active),
+            Tx in (Const, Active), Ty in (Const, Active),
             Tz in (Const, Active)
 
             test_reverse(Bijectors.find_alpha, RT, (x, Tx), (y, Ty), (z, Tz))

test/bijectors/product_bijector.jl

@@ -39,7 +39,7 @@ has_square_jacobian(b, x) = Bijectors.output_size(b, x) == size(x)
             y,
             logjac,
             changes_of_variables_test=has_square_jacobian(b, xs[1]),
-            test_not_identity=!isidentity,
+            test_not_identity=(!isidentity),
         )
     end
 
@@ -63,7 +63,7 @@ has_square_jacobian(b, x) = Bijectors.output_size(b, x) == size(x)
             y,
             logjac,
             changes_of_variables_test=has_square_jacobian(b, xs[1]),
-            test_not_identity=!isidentity,
+            test_not_identity=(!isidentity),
         )
     end
 end

test/bijectors/rational_quadratic_spline.jl

@@ -46,7 +46,7 @@ using LogExpFunctions
 
         # Outside of domain
         x = 5.0
-        test_bijector(b, -x; y=-x, logjac=0)
+        test_bijector(b, -x; y=(-x), logjac=0)
         test_bijector(b, x; y=x, logjac=0)
 
         # multivariate