diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml new file mode 100644 index 0000000000..5ffdb3a9bd --- /dev/null +++ b/.JuliaFormatter.toml @@ -0,0 +1,5 @@ +margin = 80 +indent = 4 +always_for_in = true +whitespace_typedefs = true +whitespace_ops_in_indices = true diff --git a/.dev/Manifest-v1.11.toml b/.dev/Manifest-v1.11.toml deleted file mode 100644 index 220f1226f7..0000000000 --- a/.dev/Manifest-v1.11.toml +++ /dev/null @@ -1,121 +0,0 @@ -# This file is machine-generated - editing it directly is not advised - -julia_version = "1.11.3" -manifest_format = "2.0" -project_hash = "b280bcf3b481823c97fa1a62c1b5e65114b8fa18" - -[[deps.Base64]] -uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f" -version = "1.11.0" - -[[deps.CSTParser]] -deps = ["Tokenize"] -git-tree-sha1 = "0157e592151e39fa570645e2b2debcdfb8a0f112" -uuid = "00ebfdb7-1f24-5e51-bd34-a7502290713f" -version = "3.4.3" - -[[deps.CommonMark]] -deps = ["Crayons", "PrecompileTools"] -git-tree-sha1 = "3faae67b8899797592335832fccf4b3c80bb04fa" -uuid = "a80b9123-70ca-4bc0-993e-6e3bcb318db6" -version = "0.8.15" - -[[deps.Compat]] -deps = ["TOML", "UUIDs"] -git-tree-sha1 = "8ae8d32e09f0dcf42a36b90d4e17f5dd2e4c4215" -uuid = "34da2185-b29b-5c13-b0c7-acf172513d20" -version = "4.16.0" - - [deps.Compat.extensions] - CompatLinearAlgebraExt = "LinearAlgebra" - - [deps.Compat.weakdeps] - Dates = "ade2ca70-3891-5945-98fb-dc099432e06a" - LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" - -[[deps.Crayons]] -git-tree-sha1 = "249fe38abf76d48563e2f4556bebd215aa317e15" -uuid = "a8cc5b0e-0ffa-5ad4-8c14-923d3ee1735f" -version = "4.1.1" - -[[deps.DataStructures]] -deps = ["Compat", "InteractiveUtils", "OrderedCollections"] -git-tree-sha1 = "1d0a14036acb104d9e89698bd408f63ab58cdc82" -uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8" -version = "0.18.20" - -[[deps.Dates]] -deps = ["Printf"] -uuid = "ade2ca70-3891-5945-98fb-dc099432e06a" -version = "1.11.0" - -[[deps.Glob]] -git-tree-sha1 = "97285bbd5230dd766e9ef6749b80fc617126d496" -uuid = "c27321d9-0574-5035-807b-f59d2c89b15c" -version = "1.3.1" - -[[deps.InteractiveUtils]] -deps = ["Markdown"] -uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240" -version = "1.11.0" - -[[deps.JuliaFormatter]] -deps = ["CSTParser", "CommonMark", "DataStructures", "Glob", "PrecompileTools", "TOML", "Tokenize"] -git-tree-sha1 = "59cf7ad64f1b0708a4fa4369879d33bad3239b56" -uuid = "98e50ef6-434e-11e9-1051-2b60c6c9e899" -version = "1.0.62" - -[[deps.Markdown]] -deps = ["Base64"] -uuid = "d6f4376e-aef5-505a-96c1-9c027394607a" -version = "1.11.0" - -[[deps.OrderedCollections]] -git-tree-sha1 = "12f1439c4f986bb868acda6ea33ebc78e19b95ad" -uuid = "bac558e1-5e72-5ebc-8fee-abe8a469f55d" -version = "1.7.0" - -[[deps.PrecompileTools]] -deps = ["Preferences"] -git-tree-sha1 = "5aa36f7049a63a1528fe8f7c3f2113413ffd4e1f" -uuid = "aea7be01-6a6a-4083-8856-8a6e6704d82a" -version = "1.2.1" - -[[deps.Preferences]] -deps = ["TOML"] -git-tree-sha1 = "9306f6085165d270f7e3db02af26a400d580f5c6" -uuid = "21216c6a-2e73-6563-6e65-726566657250" -version = "1.4.3" - -[[deps.Printf]] -deps = ["Unicode"] -uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7" -version = "1.11.0" - -[[deps.Random]] -deps = ["SHA"] -uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c" -version = "1.11.0" - -[[deps.SHA]] -uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce" -version = "0.7.0" - -[[deps.TOML]] -deps = ["Dates"] -uuid = "fa267f1f-6049-4f14-aa54-33bafae1ed76" -version = "1.0.3" - -[[deps.Tokenize]] -git-tree-sha1 = "468b4685af4abe0e9fd4d7bf495a6554a6276e75" -uuid = "0796e94c-ce3b-5d07-9a54-7f471281c624" -version = "0.5.29" - -[[deps.UUIDs]] -deps = ["Random", "SHA"] -uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4" -version = "1.11.0" - -[[deps.Unicode]] -uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5" -version = "1.11.0" diff --git a/.dev/Manifest.toml b/.dev/Manifest.toml deleted file mode 100644 index 0d228156f6..0000000000 --- a/.dev/Manifest.toml +++ /dev/null @@ -1,113 +0,0 @@ -# This file is machine-generated - editing it directly is not advised - -julia_version = "1.10.8" -manifest_format = "2.0" -project_hash = "b280bcf3b481823c97fa1a62c1b5e65114b8fa18" - -[[deps.Base64]] -uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f" - -[[deps.CSTParser]] -deps = ["Tokenize"] -git-tree-sha1 = "0157e592151e39fa570645e2b2debcdfb8a0f112" -uuid = "00ebfdb7-1f24-5e51-bd34-a7502290713f" -version = "3.4.3" - -[[deps.CommonMark]] -deps = ["Crayons", "PrecompileTools"] -git-tree-sha1 = "3faae67b8899797592335832fccf4b3c80bb04fa" -uuid = "a80b9123-70ca-4bc0-993e-6e3bcb318db6" -version = "0.8.15" - -[[deps.Compat]] -deps = ["TOML", "UUIDs"] -git-tree-sha1 = "8ae8d32e09f0dcf42a36b90d4e17f5dd2e4c4215" -uuid = "34da2185-b29b-5c13-b0c7-acf172513d20" -version = "4.16.0" - - [deps.Compat.extensions] - CompatLinearAlgebraExt = "LinearAlgebra" - - [deps.Compat.weakdeps] - Dates = "ade2ca70-3891-5945-98fb-dc099432e06a" - LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" - -[[deps.Crayons]] -git-tree-sha1 = "249fe38abf76d48563e2f4556bebd215aa317e15" -uuid = "a8cc5b0e-0ffa-5ad4-8c14-923d3ee1735f" -version = "4.1.1" - -[[deps.DataStructures]] -deps = ["Compat", "InteractiveUtils", "OrderedCollections"] -git-tree-sha1 = "1d0a14036acb104d9e89698bd408f63ab58cdc82" -uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8" -version = "0.18.20" - -[[deps.Dates]] -deps = ["Printf"] -uuid = "ade2ca70-3891-5945-98fb-dc099432e06a" - -[[deps.Glob]] -git-tree-sha1 = "97285bbd5230dd766e9ef6749b80fc617126d496" -uuid = "c27321d9-0574-5035-807b-f59d2c89b15c" -version = "1.3.1" - -[[deps.InteractiveUtils]] -deps = ["Markdown"] -uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240" - -[[deps.JuliaFormatter]] -deps = ["CSTParser", "CommonMark", "DataStructures", "Glob", "PrecompileTools", "TOML", "Tokenize"] -git-tree-sha1 = "59cf7ad64f1b0708a4fa4369879d33bad3239b56" -uuid = "98e50ef6-434e-11e9-1051-2b60c6c9e899" -version = "1.0.62" - -[[deps.Markdown]] -deps = ["Base64"] -uuid = "d6f4376e-aef5-505a-96c1-9c027394607a" - -[[deps.OrderedCollections]] -git-tree-sha1 = "12f1439c4f986bb868acda6ea33ebc78e19b95ad" -uuid = "bac558e1-5e72-5ebc-8fee-abe8a469f55d" -version = "1.7.0" - -[[deps.PrecompileTools]] -deps = ["Preferences"] -git-tree-sha1 = "5aa36f7049a63a1528fe8f7c3f2113413ffd4e1f" -uuid = "aea7be01-6a6a-4083-8856-8a6e6704d82a" -version = "1.2.1" - -[[deps.Preferences]] -deps = ["TOML"] -git-tree-sha1 = "9306f6085165d270f7e3db02af26a400d580f5c6" -uuid = "21216c6a-2e73-6563-6e65-726566657250" -version = "1.4.3" - -[[deps.Printf]] -deps = ["Unicode"] -uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7" - -[[deps.Random]] -deps = ["SHA"] -uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c" - -[[deps.SHA]] -uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce" -version = "0.7.0" - -[[deps.TOML]] -deps = ["Dates"] -uuid = "fa267f1f-6049-4f14-aa54-33bafae1ed76" -version = "1.0.3" - -[[deps.Tokenize]] -git-tree-sha1 = "468b4685af4abe0e9fd4d7bf495a6554a6276e75" -uuid = "0796e94c-ce3b-5d07-9a54-7f471281c624" -version = "0.5.29" - -[[deps.UUIDs]] -deps = ["Random", "SHA"] -uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4" - -[[deps.Unicode]] -uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5" diff --git a/.dev/Project.toml b/.dev/Project.toml deleted file mode 100644 index 71708c8046..0000000000 --- a/.dev/Project.toml +++ /dev/null @@ -1,5 +0,0 @@ -[deps] -JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899" - -[compat] -JuliaFormatter = "1" diff --git a/.dev/clima_formatter_options.jl b/.dev/clima_formatter_options.jl deleted file mode 100644 index 1db65e8c7d..0000000000 --- a/.dev/clima_formatter_options.jl +++ /dev/null @@ -1,8 +0,0 @@ -clima_formatter_options = ( - indent = 4, - margin = 80, - always_for_in = true, - whitespace_typedefs = true, - whitespace_ops_in_indices = true, - remove_extra_newlines = false, -) diff --git a/.dev/climaformat.jl b/.dev/climaformat.jl index 713a5189dd..432b366ef9 100644 --- a/.dev/climaformat.jl +++ b/.dev/climaformat.jl @@ -1,85 +1,14 @@ #!/usr/bin/env julia -# -# This is an adapted version of format.jl from JuliaFormatter with the -# following license: -# -# MIT License -# Copyright (c) 2019 Dominique Luna -# -# Permission is hereby granted, free of charge, to any person obtaining a -# copy of this software and associated documentation files (the -# "Software"), to deal in the Software without restriction, including -# without limitation the rights to use, copy, modify, merge, publish, -# distribute, sublicense, and/or sell copies of the Software, and to permit -# persons to whom the Software is furnished to do so, subject to the -# following conditions: -# -# The above copyright notice and this permission notice shall be included -# in all copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -# NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, -# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR -# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE -# USE OR OTHER DEALINGS IN THE SOFTWARE. -# -using Pkg -Pkg.activate(@__DIR__) -Pkg.instantiate() -using JuliaFormatter - -include("clima_formatter_options.jl") - -help = """ -Usage: climaformat.jl [flags] [FILE/PATH]... - -Formats the given julia files using the CLIMA formatting options. If paths -are given it will format the julia files in the paths. Otherwise, it will -format all changed julia files. - - -v, --verbose - Print the name of the files being formatted with relevant details. - - -h, --help - Print this message. -""" - -function parse_opts!(args::Vector{String}) - i = 1 - opts = Dict{Symbol, Union{Int, Bool}}() - while i ≤ length(args) - arg = args[i] - if arg[1] != '-' - i += 1 - continue - end - if arg == "-v" || arg == "--verbose" - opt = :verbose - elseif arg == "-h" || arg == "--help" - opt = :help - else - error("invalid option $arg") - end - if opt in (:verbose, :help) - opts[opt] = true - deleteat!(args, i) - end - end - return opts -end - -opts = parse_opts!(ARGS) -if haskey(opts, :help) - write(stdout, help) - exit(0) -end -if isempty(ARGS) - filenames = readlines(`git ls-files "*.jl"`) -else - filenames = ARGS -end - -format(filenames; clima_formatter_options..., opts...) +println("climaformat.jl has been discontinued in favor of JuliaFormatter") +println("To use JuliaFormatter, add it to your base environment with: ") +println() +println("julia -e 'using Pkg. Pkg.add(\"JuliaFormatter\")'") +println() +println("Then, format your current package with") +println() +println("using JuliaFormatter; format(\".\")") +println() +println("in a Julia REPL.") +println("See documentation to read more about this change") +println("This file will be removed in future releases") diff --git a/.dev/pre-commit b/.dev/pre-commit deleted file mode 100644 index 0e56ed0804..0000000000 --- a/.dev/pre-commit +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/env julia -# -# Called by git-commit with no arguments. This checks to make sure that all -# .jl files are indented correctly before a commit is made. -# -# To enable this hook, make this file executable and copy it in -# $GIT_DIR/hooks. - -toplevel_directory = chomp(read(`git rev-parse --show-toplevel`, String)) - -using Pkg -Pkg.activate(joinpath(toplevel_directory, ".dev")) -Pkg.instantiate() - -using JuliaFormatter - -include(joinpath(toplevel_directory, ".dev", "clima_formatter_options.jl")) - -needs_format = false - -for diffoutput in split.(readlines(`git diff --name-status --cached`)) - status = diffoutput[1] - filename = diffoutput[end] - (!startswith(status, "D") && endswith(filename, ".jl")) || continue - - a = read(`git show :$filename`, String) - b = format_text(a; clima_formatter_options...) - - if a != b - fullfilename = joinpath(toplevel_directory, filename) - - @error """File $filename needs to be indented with: - julia $(joinpath(toplevel_directory, ".dev", "climaformat.jl")) $fullfilename - and added to the git index via - git add $fullfilename - """ - global needs_format = true - end -end - -exit(needs_format ? 1 : 0) diff --git a/.dev/up_deps.jl b/.dev/up_deps.jl index 2ca708eb2c..295c6b1a5c 100644 --- a/.dev/up_deps.jl +++ b/.dev/up_deps.jl @@ -1,36 +1,12 @@ -#= -A simple script for updating the manifest -files in all of our environments. -=# +#!/usr/bin/env julia -root = dirname(@__DIR__) -dirs = ( - root, - joinpath(root, "test"), - joinpath(root, ".dev"), - joinpath(root, "perf"), - joinpath(root, "docs"), - joinpath(root, "examples"), -) - -cd(root) do - for dir in dirs - reldir = relpath(dir, root) - @info "Updating environment `$reldir`" - cmd = if dir == root - `$(Base.julia_cmd()) --project -e """import Pkg; Pkg.update()"""` - elseif dir == joinpath(root, ".dev") - `$(Base.julia_cmd()) --project=$reldir -e """import Pkg; Pkg.update()"""` - else - `$(Base.julia_cmd()) --project=$reldir -e """import Pkg; Pkg.develop(;path=\".\"); Pkg.update()"""` - end - run(cmd) - end -end - -# https://github.com/JuliaLang/Pkg.jl/issues/3014 -for dir in dirs - cd(dir) do - rm("LocalPreferences.toml"; force = true) - end -end +println("up_dev.jl has been discontinued in favor of PkgDevTools") +println("To use PkgDevTool, add it to your base environment with: ") +println() +println("julia -e 'using Pkg. Pkg.add(\"PkgDevTools\")'") +println() +println("Then, update the manifests with") +println("using PkgDevTools; PkgDevToos.update_deps(\".\")") +println("in a Julia REPL.") +println("See documentation to read more about this change") +println("This file will be removed in future releases") diff --git a/.github/workflows/julia_formatter.yml b/.github/workflows/julia_formatter.yml index 2c9262176b..aa58b9dd05 100644 --- a/.github/workflows/julia_formatter.yml +++ b/.github/workflows/julia_formatter.yml @@ -1,41 +1,14 @@ name: JuliaFormatter on: - push: - tags: '*' pull_request: - merge_group: - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - + # this argument is not required if you don't use the `suggestion-label` input + types: [ opened, reopened, synchronize, labeled, unlabeled ] jobs: format: runs-on: ubuntu-latest - timeout-minutes: 30 steps: - - - uses: actions/checkout@v4 - - - uses: dorny/paths-filter@v3.0.2 - id: filter - with: - filters: | - julia_file_change: - - added|modified: '**.jl' - - - uses: julia-actions/setup-julia@v2 - if: steps.filter.outputs.julia_file_change == 'true' - with: - version: '1.10' - - - name: Apply JuliaFormatter - if: steps.filter.outputs.julia_file_change == 'true' - run: | - julia --project=.dev .dev/climaformat.jl . - - - name: Check formatting diff - if: steps.filter.outputs.julia_file_change == 'true' - run: | - git diff --color=always --exit-code + - uses: julia-actions/julia-format@v3 + with: + version: '1' # Set `version` to '1.0.54' if you need to use JuliaFormatter.jl v1.0.54 (default: '1') + suggestion-label: 'format-suggest' # leave this unset or empty to show suggestions for all PRs diff --git a/NEWS.md b/NEWS.md index cb2f6a466a..d44232c0f9 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,6 +4,14 @@ ClimaAtmos.jl Release Notes Main ------- +### Development + +The `.dev` was deprecated. The two utilities in this folder can be replaced with +more established and better developed tools: +- instead of `clima_format`, use `JuliaFormatter`, +- instead of `up_deps`, use `PkgDevTools`. +See the [documentation](https://clima.github.io/ClimaAtmos.jl/dev/contributor_guide/#Formatting) for more information. + ### Features ### Read CO2 from file diff --git a/docs/src/contributor_guide.md b/docs/src/contributor_guide.md index 14a576bc1b..b3160bd0ae 100644 --- a/docs/src/contributor_guide.md +++ b/docs/src/contributor_guide.md @@ -180,6 +180,59 @@ and then open `docs/build/index.html` in your favorite browser. Providing the en `JULIA_DEBUG=Documenter` will provide with more information in the documentation build process and thus help figuring out a potential bug. +## Formatting + +One of the tests consists in checking that the code is uniformly formatted. We +use [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl) to achieve +consistent formatting. Here's how to use it: + +You can install in your base environment with +``` sh +julia -e 'using Pkg; Pkg.add("JuliaFormatter")' +``` +alongside your other development tools. + +Then, you can format the package running: +``` julia +using JuliaFormatter; format(".") +``` +or just with `format(".")` if the package is already imported. + +The rules for formatting are defined in the `.JuliaFormatter.toml`. + +If you are used to formatting from the command line instead of the REPL, you can +install `JuliaFormatter` in your base environment and call +``` sh +julia -e 'using JuliaFormatter; format(".")' +``` +You could also define a shell alias +``` sh +alias julia_format_here="julia -e 'using JuliaFormatter; format(\".\")'" +``` + +!!! note + +In the past, `ClimaAtmos` used to have a `.dev/climaformat.jl` script. We moved +away from it to reduce complexity in our repository and to align with the +general tools used by the Julia community. If you are still using +`climaformat.jl`, migrate to `JuliaFormatter` (`climaformat.jl` was just a +wrapper around `JuliaFormatter`). + +## Updating environments + +The repository for `ClimaAtmos` includes several checked `Manifests.toml`. This +is to help with reproducing results. +[PkgDevTools](https://github.com/CliMA/PkgDevTools.jl) provides a convenient +system to quickly update all the `Manifests.toml`. Please, refer to the +documentation for more information. + +!!! note + +In the past, `ClimaAtmos` used to have a `.dev/up_deps.jl` script. We moved away +from it because `PkgDevTools` provides a much simpler and more efficient way to +accomplish the same result. + + ## Credits This contributor's guide is heavily based on the excellent [Oceananigans.jl contributor's guide](https://clima.github.io/OceananigansDocumentation/stable/contributing/) which is heavily based on the excellent [MetPy contributor's guide](https://github.com/Unidata/MetPy/blob/master/CONTRIBUTING.md).