Merge pull request #1484 from CliMA/js/formatter

use JuliaFormatter; remove .dev

Author: juliasloan25

.JuliaFormatter.toml

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

.dev/Project.toml

@@ -4,36 +4,14 @@ on:
   push:
     tags: '*'
   pull_request:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  merge_group:
 
 jobs:
   format:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
     steps:
-    - uses: actions/checkout@v5
-
-    - 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.11'
-
-    - 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@v4
+        with:
+          version: '1' # Set `version` to '1.0.62' if you run into issues
+          # To use the same JuliaFormatter version locally, run: `julia -e 'using Pkg; Pkg.add(PackageSpec("JuliaFormatter", v"1.0.62"))'`
+          suggestion-label: 'format-suggest' # leave this unset or empty to show suggestions for all PRs

.dev/clima_formatter_options.jl

@@ -6,6 +6,11 @@ ClimaCoupler.jl Release Notes
 
 ### ClimaCoupler features
 
+#### Use JuliaFormatter; remove .dev folder PR[#1484](https://github.com/CliMA/ClimaCoupler.jl/pull/1484)
+Use JuliaFormatter to format the repo, rather than the previous `.dev/juliaformat.jl`.
+The `.dev/` folder is removed, and a documentation page about contributing to
+ClimaCoupler.jl is added.
+
 #### Correctly set land domain with `share_surface_space = true` PR[#1464](https://github.com/CliMA/ClimaCoupler.jl/pull/1464)
 Previously, we passed but did not use arguments related to the vertical resolution
 in `make_land_domain`. Now we correctly use the provided `dz_tuple` and `n_elements_vert`.

.dev/climaformat.jl

@@ -53,8 +53,14 @@ map(
 
 # pages layout
 experiment_pages = [
-    "Sea Breeze" => map(s -> "generated/sea_breeze/$(s)", readdir(joinpath(@__DIR__, "src/generated/sea_breeze"))),
-    "AMIP" => map(s -> "generated/amip/$(s)", readdir(joinpath(@__DIR__, "src/generated/amip"))),
+    "Sea Breeze" => map(
+        s -> "generated/sea_breeze/$(s)",
+        readdir(joinpath(@__DIR__, "src/generated/sea_breeze")),
+    ),
+    "AMIP" => map(
+        s -> "generated/amip/$(s)",
+        readdir(joinpath(@__DIR__, "src/generated/amip")),
+    ),
 ]
 interface_pages = [
     "checkpointer.md",
@@ -75,9 +81,20 @@ pages = Any[
     "Coupler Interface" => interface_pages,
     "Performance" => performance_pages,
     "Model Output" => output_pages,
+    "Contributing" => "contributing.md",
 ]
 
 
-makedocs(sitename = "ClimaCoupler.jl", format = Documenter.HTML(), modules = [ClimaCoupler], pages = pages)
+makedocs(
+    sitename = "ClimaCoupler.jl",
+    format = Documenter.HTML(),
+    modules = [ClimaCoupler],
+    pages = pages,
+)
 
-deploydocs(repo = "<github.com/CliMA/ClimaCoupler.jl.git>", push_preview = true, devbranch = "main", forcepush = true)
+deploydocs(
+    repo = "<github.com/CliMA/ClimaCoupler.jl.git>",
+    push_preview = true,
+    devbranch = "main",
+    forcepush = true,
+)

.dev/hooks/pre-commit

@@ -0,0 +1,67 @@
+# Contributing
+
+Thank you for contributing to `ClimaCoupler`! We encourage Pull Requests (PRs).
+Please do not hesitate to ask questions, or to open issues if something seems amiss
+or you'd like a new feature.
+
+## Some useful tips
+- When developing code it's best to work on a branch off of the most recent main.
+This can be done by running the following commands, where "initials" corresponds to the first and last initial of the person starting the branch.
+```
+git checkout main
+git pull
+git checkout -b initials/branch_name
+```
+
+- Make sure you add tests for your code in `test/`, appropriate documentation in `docs/`,
+  and descriptive inline comments throughout the code.
+  All exported functions and structs must have docstrings.
+- When your PR is ready for review, clean up your commit history by squashing to 1 commit per PR
+  and make sure your code is current with the main branch by rebasing.
+
+## Continuous integration
+
+After rebasing your branch, you can ask for review. Fill out the template and
+provide a clear summary of what your PR does. When a PR is created or
+updated, a set of automated tests are run on the PR in our continuous
+integration (CI) system.
+
+ClimaCoupler.jl's continuous integration contains both unit tests and integration
+tests (coupled simulations).
+
+### Formatting check
+
+The `JuliaFormatter` test checks if the PR is correctly formatted according to
+the project's style guidelines. The previous `.dev/climaformat.jl` script has
+been discontinued in favor of using the JuliaFormatter package directly.
+
+To format your code, first add JuliaFormatter to your base environment:
+
+```sh
+julia -e 'using Pkg; Pkg.add(PackageSpec("JuliaFormatter", v"1.0.62"))'
+```
+
+Then, in a Julia REPL, run:
+
+```julia
+using JuliaFormatter; format(".")
+```
+
+
+### Documentation
+
+The `Documentation` test rebuilds the documentation for the PR and checks if the docs
+are consistent and generate valid output.
+
+To add internal references, for example to another documentation page or API, see the relevant
+`Documenter.jl` `@ref` [documentation page](@extref Documenter Named-@refs), example syntax:
+`[see contributor guide](@ref "Contributing")` for a page or
+`[CoupledSimulation object and constructors](@ref ClimaCoupler.Interfacer.CoupledSimulation)` for an API.
+
+To add external references, for example to another package documentation page or API, see
+the documentation of [DocumenterInterLinks](https://juliadocs.org/DocumenterInterLinks.jl/stable/).
+Example syntax: `[how to us @ref](@extref Documenter Named-@refs)`.
+
+To add a reference from the literature, see the documentation of
+[DocumenterCitations.jl](https://juliadocs.org/DocumenterCitations.jl/stable/), in short, add your reference
+to `docs/src/refs.bib` and then refer to it with this syntax `[authors1999](@citet)`.