Development Best Practices

Coding Conventions

Castro development should do its best to adhere to the following coding style guidelines.

General

Indentation should be spaces, not tabs, with 4 spaces preferred.

C++

Conditional should appear as:

if (condition)
{
    ...
}
else if (condition)
{
    ...
}
else
{
    ...
}

Documentation

C++ routines should use Doxygen style comments.

C++ functions should be documented in the header file using the style:

///
/// Description of the function
///
/// @param bar       Brief description of the variable
///
void foo(int bar) { ...

Member variables can either be documented using the above style of comment block or with a brief inline description:
```
int var; ///< Brief description after the variable
```

Castro Releases

This outlines the procedure for doing the monthly Castro release.

Castro uses submodules for dependencies, this means that, at a minimum, we must update the AMReX and Microphysics submodules monthly when we issue new releases. The releases for AMReX and Microphysics must be done first. Then navigate to each submodule directory, checkout the new tag, and then from the top-level directory of Castro do a “git add” on the external/ directory to store the new tags. So, for example, at the beginning of March 2020 we would first issue the 20.03 tag on Microphysics, and wait for AMReX to release a 20.03 tag, then do:

cd $CASTRO_HOME/external
cd amrex
git pull
git checkout 20.03
cd ..
cd Microphysics
git pull
git checkout 20.03
cd ..
git add -u .
git commit -m "Update AMReX and Microphysics to release 20.03"

Then we can proceed with issuing our own release.

Each month the development branch is merged into main and a release is tagged. This needs to be done in coordination with its submodule dependencies. The general procedure is:

Do ‘git pull’ in both main and development branches. (Use git checkout xxx to change to branch xxx.

In main branch, do git merge development. Fix any conflicts if there are any. (There should not be any conflicts unless a commit is checked into main directly without going through development.)

In main branch, commit new release notes (CHANGES.md) summarizing changes since last major release.

Tag the new release: git tag -m "Castro YY.MM" YY.MM

git push

git push --tags

git checkout development

git merge main

git push

Interim updates

When breaking changes to Microphysics occur in its development branch that Castro depends on, we must update the Microphysics submodule on the Castro development branch in the same way, replacing the git checkout statement with the latest commit hash on the Microphysics development branch. (A git submodule always tracks a specific commit/tag on the target repo – it is not configured to automatically track a particular branch.) Since such breaking changes usually are accompanied by a Castro change, it is best practice to ensure that the PRs in both Microphysics and Castro have been approved, then merge the Microphysics PR, then add the update to the Microphysics submodule to the Castro PR, then merge. A similar process applies for AMReX.

Continuous Integration

We github actions to run integration tests on the code and to build and deploy the documentation.

Currently, we run the clang static analyzer, which finds potential bugs in the code. It also runs a script to convert any tabs in the code into spaces. Both of these are run on pull requests to the Castro GitHub repo, and are run weekly on the development branch.