Adding tooling for JuliaFormatter. (#2323)

* Adding new environment for tooling.

* Adding `JuliaFormatter` config.

* Added file for formatting.

* Adding CI for JuliaFormatter.

* Adding a custom pre-commit hook, and a new script which sets up the
hook.

* Removing Flux from tooling deps, and instantiating environment from
`setup.jl`.

* Adding shebang for hook to work on windows.

* Instantiating from `flux_format.jl` too.

* Minor fixes in JuliaFormatter CI.

* Adding formatting steps to `CONTRIBUTING.md`.

* Removing the `--verbose` option from the hook, and printing some useful
text during formatting.

* Minor fix in formatting script.

.JuliaFormatter.toml

@@ -0,0 +1,6 @@
+indent = 4
+margin = 80
+always_for_in = true
+whitespace_typedefs = true
+whitespace_ops_in_indices = true
+remove_extra_newlines = false

.githooks/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+julia --color=yes dev/flux_format.jl .

.github/workflows/JuliaFormatter.yml

@@ -0,0 +1,40 @@
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+
+jobs:
+  format:
+    runs-on: ubuntu-20.04
+    timeout-minutes: 30
+    steps:
+    - uses: actions/[email protected]
+
+    - uses: dorny/[email protected]
+      id: filter
+      with:
+        filters: |
+          julia_file_change:
+            - added|modified: '**.jl'
+
+    - uses: julia-actions/setup-julia@latest
+      if: steps.filter.outputs.julia_file_change == 'true'
+      with:
+        version: 1.9
+
+    - name: Apply JuliaFormatter
+      if: steps.filter.outputs.julia_file_change == 'true'
+      run: |
+        julia --color=yes dev/flux_format.jl --verbose .
+
+    - name: Check formatting diff
+      if: steps.filter.outputs.julia_file_change == 'true'
+      run: |
+        git diff --color=always --exit-code

CONTRIBUTING.md

@@ -154,4 +154,20 @@ The following table shows how the Flux code is organized:
 | docs  | Documentation site  |
 | paper  | Paper that describes Flux |
 | src    |  Source for Flux  |
-| test   |  Test suites  |
+| test   |  Test suites  |
+
+### Julia Formatter
+
+Flux also uses it's own formatting style (see `dev/flux_format.jl`), with the style defined in the `.JuliaFormatter.toml` config file. All contributors must make sure to conform to this formatting style. To do this, run the following setup file on your local repository:
+
+```julia
+julia dev/setup.jl
+```
+
+This will setup the tooling environment (defined in the `dev/` directory), and will set up a hook to run the formatter before any changes are committed. You can also manually format the codebase by running
+
+```julia
+julia dev/flux_format.jl --verbose .
+```
+
+Flux's CI will also test whether any changes you make conform to this formatting style whenever any pull request is made.

dev/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Git = "d7ba0133-e1db-5d97-8f8c-041e4b3a1eb2"
+JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"

dev/flux_format.jl

@@ -0,0 +1,57 @@
+using Pkg
+Pkg.activate(@__DIR__)
+Pkg.instantiate()
+
+using JuliaFormatter
+
+help = """
+Usage: flux_format.jl [flags] [FILE/PATH]...
+
+Formats the given julia files using the Flux formatting options.
+If paths are given instead, it will format all *.jl files under
+the paths. If nothing is given, all changed julia files are formatted.
+
+    -v, --verbose
+        Print the name of the files being formatted with relevant details.
+
+    -h, --help
+        Print this help message.
+"""
+
+options = Dict{Symbol, Bool}()
+indices_to_remove = []      # used to delete options once processed
+
+for (index, arg) in enumerate(ARGS)
+    if arg[1] != '-'
+        continue
+    end
+    if arg in ["-v", "--verbose"]
+        opt = :verbose
+        push!(indices_to_remove, index)
+    elseif arg in ["-h", "--help"] 
+        opt = :help 
+        push!(indices_to_remove, index)
+    else
+        error("Option $arg is not supported.")
+    end
+    options[opt] = true
+end
+
+# remove options from args
+deleteat!(ARGS, indices_to_remove)
+
+# print help message if asked
+if haskey(options, :help)
+    write(stdout, help)
+    exit(0)
+end
+
+# otherwise format files
+if isempty(ARGS)
+    filenames = readlines(`git ls-files "*.jl"`)
+else
+    filenames = ARGS
+end
+
+write(stdout, "Formatting in progress.\n")
+format(filenames; options...)

dev/setup.jl

@@ -0,0 +1,14 @@
+# instantiate the environment
+using Pkg
+Pkg.activate(@__DIR__)
+Pkg.instantiate()
+
+# setup the custom git hook
+using Git
+
+# set the local hooks path
+const git = Git.git()
+run(`$git config --local core.hooksPath .githooks/`)
+
+# set file permission for hook
+Base.Filesystem.chmod(".githooks", 0o777; recursive = true)