Skip to content

Latest commit

 

History

History
50 lines (37 loc) · 3.47 KB

README-for-Developers.md

File metadata and controls

50 lines (37 loc) · 3.47 KB

README for developers

This file contains some notes for the developers to be aware of. This is by far not exhaustive or very structured. See it as a dump for links and information relevant for Julia package development!

Julia specific conventions

Developing packages in Julia there are certain conventions. Although not aware of all of them, the following paragraphs outline some resources helpful in learning them.

Code Style: https://github.com/invenia/BlueStyle

Debugging/Coding workflow: some tutorial to get into the hang of using VSCode Studio for Julia package development: https://techytok.com/lesson-workflow/

DevOps

_Git Flow: Main project is develop. Features are to be developed in branches and merged. For further information, see: https://discourse.julialang.org/t/good-practices-for-package-development-in-the-julia-ecosystem/8175/2

Commit messages: There are standards to commit messages. Various info is summarized in the file .git-commit-msg-template. It also serves as a template for commit messages: execute git config commit.template .git-commit-msg-template to make it the standard commit message for the repository, which will be shown each time you git commit.

Version numbering: https://semver.org

Before pushing: you could run test suite locally and test generation of documentation. To do so use julia --project=docs docs/make.jl or julia --project=. test/runtests.jl (as could be inferred from .github/workflows/Documentation.yml) Note: actually according to (https://discourse.julialang.org/t/add-test-as-a-dependency-of-project/89043/7 and https://discourse.julialang.org/t/is-there-a-difference-under-the-hood-between-running-code-via-a-jl-file-and-running-code-via-test-name-of-pkg/38097/3?u=fabern) an alternative way to better locally reproduce the empty environemnt on CI is by doing: julia --project=. using Pkg; Pkg.test("LWFBrook90"), since Pkg.test generates a new environment not including the default environment.

Testing: Testing asserts the functioning of the program as expected. Combined with continuous integration, changes to the functioning are detected as early as possible. There are different types of tests in LWFBrook90.jl:

  • Unit testing asserts that individual pieces of a project work as expected. (developers perspective)
  • Integration testing asserts that they fit together as expected. Also known as functional tests, they cover entire use cases (user perspective). For LWFBrook90.jl these are tests that are compared to e.g. LWFBrook90R or Hydrus.
  • Regression testing asserts that behavior is unchanged over time. Also known as reference tests.

See https://eth-vaw-glaciology.github.io/course-101-0250-00/lecture6/#unit_testing_and_reference_tests_in_julia for some hands-on explanations.

Further some performance metrics are also included in the integration tests to assert the effect of code refactoring not only on correctness of results but also on performance.

Code coverage: Whether code coverage report should only use unit tests or a combined value of all test types is debatable.