Contributing

This is a FOSS project — anyone interested in using, developing, or contributing is welcome. The project follows a KISS (Keep It Simple and Stupid) philosophy.

Reporting Issues

• Open a ticket on the repository GitHub Issues page
• Clearly describe the problem, including steps to reproduce for bugs
• Note the earliest version you know has the issue

Pull Requests

1. Fork the repository on GitHub
2. Create a topic branch from master:

   git checkout -b fix/master/my_contribution master

3. Test your changes with fobis build --mode tests-gnu-debug && scripts/run_tests.sh (as the CI) or with CMake and ctest (see the installation guide). A new test program must print Are all tests passed? T (or F) and end with if (.not.all(test_passed)) error stop 'some tests failed': the test runners judge it by its exit status
4. Check for unnecessary whitespace: git diff --check
5. Submit a pull request with a clear commit message

Documentation examples

Every program shown in the documentation is in docs/examples/src/: the pages include its code, its output and its images, generated by compiling and running it, never written by hand.

bash scripts/docs_examples.sh                                  # rebuild the library, build and run every example
PVPYTHON=/path/to/pvpython bash scripts/docs_examples.sh       # also render the VTK files with ParaView

The marker comments of a program (!run, !region, !cast, !render, ...) say what is generated: they are described at the top of scripts/docs_examples.sh. Commit docs/examples/ with the change: the Docs examples workflow fails when the committed snippets, outputs or terminal images differ from what the programs produce (it uses gfortran 14: FC=gfortran-14 to match it). The ParaView renders (*.png, *.gif) are regenerated only where ParaView is installed; keep the examples small, their meshes are made to be looked at.

Fortran Coding Style

• Clarity over brevity: real :: gas_ideal_air is better than real :: gia
• Single-character variable names only for loop counters
• Name all constants
• implicit none in every module and program
• Declare intent for all procedure arguments, ordered: pass arg → inout → in → out → optional
• Indent with two spaces (not tabs)
• No trailing whitespace; blank lines must contain no spaces
• Use >, <, == instead of .gt., .lt., .eq.
• Avoid Windows-style CRLF line endings

Recommended git whitespace settings

[color]
  ui = true
[color "diff"]
  whitespace = red reverse
[core]
  whitespace = fix,-indent-with-non-tab,trailing-space,cr-at-eol

Commit style

Use Conventional Commits so that CHANGELOG.md is generated automatically from the git log:

Prefix	Purpose	Changelog section
feat:	New feature or capability	New features
fix:	Bug fix	Bug fixes
perf:	Performance improvement	Performance
refactor:	Code restructuring	Refactoring
docs:	Documentation only	Documentation
test:	Tests	Testing
build:	Build system	Build system
ci:	CI/CD pipeline	CI/CD
chore:	Maintenance	Miscellaneous

Append ! for breaking changes (feat!:, fix!:). Reference issues with #123 — they are auto-linked.

feat(writers): add PolyData (vtp) and PPolyData (pvtp) topologies
fix(appended): correct the offsets of base64 compressed arrays (#123)
feat!: rename write_geo to write_geometry

---

Creating a release

Releases are made from master (trunk based) with scripts/release.sh, which needs git-cliff (cargo install git-cliff, or a binary from its releases page):

scripts/release.sh --patch    # X.Y.Z → X.Y.Z+1
scripts/release.sh --minor    # X.Y.Z → X.Y+1.0
scripts/release.sh --major    # X.Y.Z → X+1.0.0
scripts/release.sh v2.1.0     # explicit version (the v prefix is optional)

The script first checks that you are on master, up to date with origin, with a clean working tree, and that the new tag does not exist yet. After your confirmation it:

1. Regenerates CHANGELOG.md from the git log with git-cliff
2. Updates VERSION, and the version of fpm.toml (without the v prefix)
3. Commits them with chore(release): vX.Y.Z
4. Creates the annotated tag vX.Y.Z
5. Pushes master and the new tag

If a step fails, it prints the commands to resume or to undo what was done.

Pushing master runs the CI (tests and coverage) and the Docs workflow (deploys this site) on the release commit, as for any push. Pushing the tag runs the release workflow (.github/workflows/release.yml), which:

• Packages the source tarball VTKFortran-vX.Y.Z.tar.gz
• Publishes a GitHub release with the CHANGELOG.md section of the version as release notes, the tarball and scripts/install.sh attached
• Smoke-tests the published release (.github/workflows/install.yml): install.sh with the CMake and FoBiS.py builds, and an fpm build of the tag