diff --git a/docs/make.jl b/docs/make.jl index 092ca4a..5489017 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -6,13 +6,12 @@ using DocumenterInterLinks links = InterLinks("Trixi" => ("https://trixi-framework.github.io/Trixi.jl/stable/", "https://trixi-framework.github.io/Trixi.jl/stable/objects.inv")) - # Copy list of authors to not need to synchronize it manually authors_text = read(joinpath(dirname(@__DIR__), "AUTHORS.md"), String) -authors_text = replace(authors_text, "in the [LICENSE.md](LICENSE.md) file" => "under [License](@ref)") +authors_text = replace(authors_text, + "in the [LICENSE.md](LICENSE.md) file" => "under [License](@ref)") write(joinpath(@__DIR__, "src", "authors.md"), authors_text) - DocMeta.setdocmeta!(TrixiShallowWater, :DocTestSetup, :(using TrixiShallowWater); recursive = true) @@ -51,7 +50,6 @@ open(joinpath(@__DIR__, "src", "contributing.md"), "w") do io println(io, line) end end - makedocs(; modules = [TrixiShallowWater], @@ -67,6 +65,8 @@ makedocs(; "Home" => "index.md", "Installation" => "installation.md", "Tutorials" => "tutorial.md", + "Advanced topics & developers" => ["Development" => "development.md" + "Testing" => "testing.md"], "Authors" => "authors.md", "Contributing" => "contributing.md", "Code of Conduct" => "code_of_conduct.md", diff --git a/docs/src/development.md b/docs/src/development.md new file mode 100644 index 0000000..edaee30 --- /dev/null +++ b/docs/src/development.md @@ -0,0 +1,47 @@ +# Development + +This page contains some helpful information for the development of TrixiShallowWater.jl. Further +information about helpful tools for package development in Julia can be found on the +[development page](https://trixi-framework.github.io/Trixi.jl/stable/development/) of the Trixi.jl docs + +## Releasing a new version of TrixiShallowWater + +- Check whether everything is okay, tests pass etc. +- Set the new version number in `Project.toml` according to the Julian version of semver. + Commit and push. +- Comment `@JuliaRegistrator register` on the commit setting the version number. +- `JuliaRegistrator` will create a PR with the new version in the General registry. + Wait for it to be merged. +- Increment the version number in `Project.toml` again with suffix `-pre`. For example, + if you have released version `v0.2.0`, use `v0.2.1-pre` as new version number. + + + +## Preview the documentation + +You can build the documentation of TrixiShallowWater.jl locally by running +```bash +julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' +julia --project=docs --color=yes docs/make.jl +``` +from the TrixiShallowWater.jl main directory. Then, you can look at the html files generated in +`docs/build`. + + + +## Developing with a local Trixi.jl version + +TrixiShallowWater.jl has Trixi.jl as a dependency and uses Trixi.jl's implementation. +When developing TrixiShallowWater.jl, one may want to change functions in Trixi.jl to allow them to be reused +in TrixiShallowWater.jl. +To use a locally modified Trixi.jl clone instead of a Trixi.jl release, one can tell Pkg +to use the local source code of Trixi.jl instead of a registered version by running +```julia-repl +using Pkg +Pkg.develop(PackageSpec(path="path/to/Trixi.jl")) +``` + +To switch back from a local version to a Trixi.jl release run +```julia-repl +Pkg.free("Trixi") +``` diff --git a/docs/src/testing.md b/docs/src/testing.md new file mode 100644 index 0000000..4de5568 --- /dev/null +++ b/docs/src/testing.md @@ -0,0 +1,80 @@ +# Testing + +During the development of TrixiShallowWater.jl, we rely on +[continuous testing](https://en.wikipedia.org/wiki/Continuous_testing) to ensure +that modifications or new features do not break existing +functionality or add other errors. In the main +[TrixiShallowWater](https://github.com/trixi-framework/TrixiShallowWater.jl) repository, this is facilitated by +[GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions), +which allows to run tests automatically upon certain events. When, how, and what +is tested by GitHub Actions is controlled by the workflow file +[`.github/workflows/ci.yml`](https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/.github/workflows/ci.yml). +In TrixiShallowWater.jl tests are triggered by +* each `git push` to `main` and +* each `git push` to any pull request. +Besides checking functionality, we also analyze the [Test coverage](@ref) to +ensure that we do not miss important parts during testing. + +!!! note "Test and coverage requirements" + Before merging a pull request (PR) to `main`, we require that + * the code passes all functional tests + * code coverage does not decrease. + + +## Testing setup +The entry point for all testing is the file +[`test/runtests.jl`](https://github.com/trixi-framework/TrixiShallowWater.jl/blob/main/test/runtests.jl), +which is run by the automated tests and which can be triggered manually by +executing +```julia +julia> using Pkg; Pkg.test("TrixiShallowWater") +``` +in the REPL. Since there already exist many tests, we have split them up into +multiple files in the `test` directory to allow for faster testing of individual +parts of the code. +Thus in addition to performing all tests, you can also just `include` one of the +files named `test_xxx.jl` to run only a specific subset, e.g., +```julia +julia> # Run all test for the TreeMesh1D + include(joinpath("test", "test_tree_1d.jl")) +``` + + +## Adding new tests +We use Julia's built-in [unit testing capabilities](https://docs.julialang.org/en/v1/stdlib/Test/) +to configure tests. In general, newly added code must be covered by at least one +test, and all new scripts added to the `examples/` directory must be used at +least once during testing. New tests should be added to the corresponding +`test/test_xxx.jl` file. +Please study one of the existing tests and stay consistent to the current style +when creating new tests. + +Since we want to test as much as possible, we have a lot of tests and +frequently create new ones. Therefore, new tests should be as +short as reasonably possible, i.e., without being too insensitive to pick up +changes or errors in the code. + +When you add new tests, please check whether all CI jobs still take approximately +the same time. If the job where you added new tests takes much longer than +everything else, please consider moving some tests from one job to another +(or report this incident and ask the main developers for help). + +!!! note "Test duration" + As a general rule, tests should last **no more than 10 seconds** when run + with a single thread and after compilation (i.e., excluding the first run). + + +## Test coverage +In addition to ensuring that the code produces the expected results, the +automated tests also record the +[code coverage](https://en.wikipedia.org/wiki/Code_coverage). The resulting +coverage reports, i.e., which lines of code were executed by at least one test +and are thus considered "covered" by testing, are automatically uploaded to +[Coveralls](https://coveralls.io) for easy analysis. Typically, you see a number +of Coveralls results at the bottom of each pull request: One for each parallel +job (see [Testing setup](@ref)), which can usually be ignored since they only +cover parts of the code by definition, and a cumulative coverage result named +`coverage/coveralls`. The "Details" link takes you to a detailed report on +which lines of code are covered by tests, which ones are missed, and especially +which *new* lines the pull requests adds to TrixiShallowWater.jl's code base that are not yet +covered by testing. \ No newline at end of file