Skip to content

TPS developer tips

Jump to bottom
Todd Oliver edited this page Aug 23, 2023 · 5 revisions

This page contains a few tips on developing within tps. The goal is for new developers to understand some expectations and best practices for the repository. To begin, this page is simply a list of thoughts. Possibly in the future it will be organized into a more coherent guide. Either way, it is a work in progress. If you have useful tips, feel free to edit or add content, or contact oliver@oden.utexas.edu with suggestions.

Obtaining the code for development purposes

Assuming you have write permission on the tps repo, clone the code (e.g., using ssh keys):

git clone git@github.com:pecos/tps.git

Then, create a development branch for yourself and push your work there.

If you do not have permission to create branches, then you can develop on a fork of tps. If you'd like to have write permission, contact Todd Oliver (oliver@oden.utexas.edu). The rest of this page assumes you are developing within the tps repo, although most of the comments apply equally to forks.

Keeping the repo clean

Please only add/commit/push code and minimal data you need (e.g., for testing). Other kruft (e.g., any files generated by the build, such as executables or libraries, random file system foo, like .DS_Store on mac, etc) should not be on the repo. A decent rule of thumb is that if it is automatically generated, it doesn't go on the repo. For files that are large, think twice if it is really necessary. For instance, the tps repo isn't for housing your simulation results. But, some large files, such as meshes and restart files, are necessary for testing. These should be handled with git large file storage (git lfs).

Pull Requests

All development work should start on a branch and be incorporated ("merged") back into main via a pull request. The basic workflow is as follows:

  1. Create a branch: git checkout -b dev-my-new-feature where dev-my-new-feature is the name of your branch.
  2. Develop your code
  3. Test your code
  4. Create a pull request through github (see github pull request documentation for help creating a PR).

After you create a PR, the tps continuous integration (CI) test suite will run. This involves building the code and running tests on various platforms. If any of these tests fail, you can update your branch (in your development environment) and push your changes to github, which will automatically update the PR and run the test suite again.

While it is not required---i.e., there is no automated check at this point---we generally prefer to maintain a linear commit history for tps. To make this easy, we recommend rebasing your branch on main prior to creating a PR.

The test suite

The test suite includes three types of checks:

  1. Whether the tps containers (defined in Dockerfiles that live here) have been modified such that the containers need to be regenerated.
  2. Whether the code conforms to the tps style
  3. Whether the code compiles and passes a test suite on various platforms

The workflows are (mostly) executed through GitHub Actions and are defined by yaml files under the .github/workflows directory of the tps repo (here).

Container check

The tps repo maintains Dockerfile(s) defining containers with the tps dependencies. The containers themselves are stored on dockerhub under the pecosut user, see here. If a PR contains changes to the Dockerfiles, GitHub Actions will automatically regenerate the container and push it to dockerhub. For more about the tps containers, see below.

Style check

The style check ensures that the code conforms to some style guidelines. This check can be run locally with make style. Specifically, executing make style within your tps build directory---wherever you run make to compile tps---will run the style check. The style check is based on the Google C++ style guide and uses the Google cpplint.py utility. For more details, see the style target defined here and the cpplint.py script here. If make style identifies style errors, you may fix them manually, or run make enforcestyle. The enforcestyle target modifies your code locally, using clang-format, to conform to the style guideline. Note that clang-format may make changes in addition to those necessary for make style to pass.

Build and test

Finally, the remaining checks configure, build, and test tps (i.e., run configure, make, make check). You are encouraged to run make check in your development environment prior to creating a PR in order to find and fix obvious failures prior to the PR. However, since the tests will run on a variety of platforms, this does not guarentee that all the tests will pass, and that is fine. If there are failures, simply fix them and push the update to github, which will kill any tests still running and launch the tests again using the updated code.

Future discussion items

  1. More info on containers
  2. Notes on rebase (and why we love it)
  3. Style suggestions
  4. How to clean up when you add files you shouldn't
  5. How to add tests to the test suite
  6. How to edit or add workflows to github actions
Clone this wiki locally