Published: Sep 15, 2021 by Peter Hill
FORD is a documentation generator for Fortran projects, and is widely used by the scientific Fortran community. It is similar to the popular Doxygen tool, but is designed from the ground up for Fortran. At the time of writing, FORD has 280 stars on GitHub and over 100 forks.
The current maintainers found they had less and less time to devote to FORD, with the result that it had been more than two years since the last release. Because this is an important community project, we have picked up maintenance of the code to ensure that it remains available and useful for everyone.
The first thing I did was to review the current state of the
project. Pull requests and bug reports had started to pile up, and
there was a rather unfortunate lack of tests. The packaging with
setup.py was a little bit out of date, although the Python community
seems to change its mind on how to do this about twice a year!
I went through each pull request (PR), tidying up any particularly egregious errors before merging them. For some PRs the community had already had some discussion as to its appropriateness, which made this job a lot easier.
Next, I used the black Python formatter to format the entire codebase to a consistent style. I really like black due to its lack of configuration options, which heads off arguments about style – just use black! I also set this up as a GitHub Action, meaning that formatting is now automatically taken care of.
After that, I began writing tests using pytest. I started out by going through the PRs that fixed bugs, writing tests for them that failed without the fix and checking the PR did indeed fix the bug. One of the major difficulties of writing tests on code that wasn’t designed with tests in mind is just getting the correct data structures set up. Here’s where pytest’s fixtures came in useful. Writing a fixture allowed me to pull out common setup code from each test function into a separate function that ran before each individual test.
In the two months we have been helping maintain FORD we have:
- reviewed and merged 33 pull requests,
- fixed 20 bugs,
- closed another 21 issues,
- added 57 tests, and
- released 1 minor version and 4 bug releases!
We also added GitHub Actions to automatically run the tests, apply black formatting, and publish the packages on PyPI when new releases are created.