From 0841ea4f0f44c03768729aa1de86407bcf352326 Mon Sep 17 00:00:00 2001 From: Siddhant Chaudhary <59536395+codetalker7@users.noreply.github.com> Date: Sun, 10 Sep 2023 16:03:24 +0530 Subject: [PATCH] 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 | 6 +++ .githooks/pre-commit | 2 + .github/workflows/JuliaFormatter.yml | 40 +++++++++++++++++++ CONTRIBUTING.md | 18 ++++++++- dev/Project.toml | 3 ++ dev/flux_format.jl | 57 ++++++++++++++++++++++++++++ dev/setup.jl | 14 +++++++ 7 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 .JuliaFormatter.toml create mode 100755 .githooks/pre-commit create mode 100644 .github/workflows/JuliaFormatter.yml create mode 100644 dev/Project.toml create mode 100644 dev/flux_format.jl create mode 100644 dev/setup.jl diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml new file mode 100644 index 0000000000..b9af0ebafa --- /dev/null +++ b/.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 diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100755 index 0000000000..2f8429e4f3 --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,2 @@ +#!/bin/sh +julia --color=yes dev/flux_format.jl . diff --git a/.github/workflows/JuliaFormatter.yml b/.github/workflows/JuliaFormatter.yml new file mode 100644 index 0000000000..3782df82f9 --- /dev/null +++ b/.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/checkout@v2.2.0 + + - uses: dorny/paths-filter@v2.9.1 + 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ce008e459b..e5f6321637 100644 --- a/CONTRIBUTING.md +++ b/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 | \ No newline at end of file +| 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. diff --git a/dev/Project.toml b/dev/Project.toml new file mode 100644 index 0000000000..2922960e2c --- /dev/null +++ b/dev/Project.toml @@ -0,0 +1,3 @@ +[deps] +Git = "d7ba0133-e1db-5d97-8f8c-041e4b3a1eb2" +JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899" diff --git a/dev/flux_format.jl b/dev/flux_format.jl new file mode 100644 index 0000000000..699a3eeaad --- /dev/null +++ b/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...) diff --git a/dev/setup.jl b/dev/setup.jl new file mode 100644 index 0000000000..a119426eac --- /dev/null +++ b/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)