An analysis library for ClimaDiagnostics (and, more generally, NetCDF files)
APACHE-2.0 License
ClimaAnalysis.jl
is a Julia library to post-process and visualize ClimaAtmos
simulations (and, more generally, NetCDF files).
Check out the documentation for more information and tutorials.
Makie
GeoMakie
times
)These guidelines aim to ensure consistent code quality, maintainability, and a
smooth collaborative workflow for ClimaAnalysis.jl
. Please, read these
guidelines even if you are familiar with other CliMA packages as there may be
some differences.
We prioritize well-tested code to guarantee ClimaAnalysis.jl
functions
reliably. Here are some principles we follow:
test
folder and are exclusively thereThis means that all the tests can be run with Pkg.test()
.
Manifest.toml
filesWhile checking in Manifest.toml
files ensures reproducibility, it also
introduces some nuisance, including:
In this repository, we have two environments:
The project environment defines the test dependencies in its extras
(to reduce
the number of environments and to avoid the "cannot merge projects" problem).
:note: Please, open an issue if you find workflow problems/friction with this system.
ClimaAnalysis.jl
defines the test dependencies directly in the main
Project.toml
. This means that the package can be tested simply by running ] test
in a Julia REPL, as shown below:
Start a Julia session in the ClimaAnalysis
directory:
julia --project
Enter Pkg
mode by typing ]
. This will change the prompt. Run test
.
When doing so, Julia
will start a new temporary environment where the tests
are run in isolation. Tests are running checking for in-bounds and for
deprecations, and this can result in code invalidation and new precompilation.
Note, the project environment does not contain the test dependencies. Therefore,
you will find that some dependencies are missing if you try "manually" run the
test in a REPL. To solve this problem, use
TestEnv. Install TestEnv
in your
base environment (julia -e 'using Pkg; Pkg.add("TestEnv")'
). Then, when you
want to use the test dependencies, activate it from your REPL with using TestEnv; TestEnv.activate()
. This will bump you to an environment where the
test dependencies are available.
:note: Please, open an issue if you find workflow problems/friction with this system.
JuliaFormatter.jl
One of the tests consists in checking that the code is uniformly formatted. We use JuliaFormatter.jl to achieve consistent formatting. Here's how to use it:
You can either install in your base environment with
julia -e 'using Pkg; Pkg.add("JuliaFormatter")'
or use it from within the TestEnv
(or base) environments (see previous section).
Then, you can format the package running:
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
julia -e 'using JuliaFormatter; format(".")'
You could also define a shell alias
alias julia_format_here="julia -e 'using JuliaFormatter; format(\".\")'"
:note: Please, open an issue if you find workflow problems/friction with this system.
Documentation is generated with Documenter.jl. We strive to have complete and up-to-date information.
To generate documentation, run
julia --project=docs docs/make.jl
Please, update the documentation if you add new features or change the behavior of existing ones.
We encourage using jldoctest
to add and test examples in docstrings.
Here's how to structure your contributions effectively:
Your pull request can contain one or multiple commits. In either cases, it is important that each commit is atomic (meaning that each commit represents a single logical change).
Please, squash commits that represent a single logical change (e.g., do not have two commits when the second just fixes the first).
Pull requests are not merged, but rebased, ensuring a linear history (this is handled automatically by GitHub).