Hey there,
It’s Robin from CFD Engine and this week I want to share some recent experiences reporting OpenFOAM issues & why “I don’t know how to fix it” isn’t a valid excuse for avoiding doing it.
I’m not a developer – I can wrangle a Shell script, but when it comes to the OpenFOAM source code, I’m completely out of my depth.
My C++ is like my French – I can read the simple bits, but you wouldn’t want me to write any.
As such I’ve been reluctant to report issues. I’m unlikely to be able to offer a solution, so pointing out an issue just felt like complaining (and complaining about open-source code just feels petty).
I’d also assumed that my kind of “help” wasn’t really needed & so I stayed clear of the bug tracker.
That changed when a client asked me to report an issue that he’d spotted. I tried to duck out of it, but he gave me all the details & asked nicely so, no excuses.
Turns out it wasn’t painful after all 👍
But that could have been a fluke so, after my recent fun with zero directories, I reported a couple of the unexpected behaviours that I’d noticed with decomposePar.
The results were the same. My issues were welcomed, discussed, investigated & acted on. One turned out to be more of a feature than a bug, but the other was fixed for my use case within days. It felt like a win, even though I had no input into the code / fix.
So, if you’re in a similar spot, here are the steps to report your issue…
The Steps
Note: I’m talking about reporting issues to ESI/OpenCFD (my preferred OpenFOAM release) your mileage may vary with The Foundation 🤷♂️
- Register for a free user account at the ESI code repository – you don’t need an account to browse/search the repository, but you do need one to report an issue;
- Search the existing issues to see if anything related to your issue has already been reported. If anything looks similar, it might be worth commenting on that issue before opening a new one;
- If not, start a new report with the big blue button;
- Give it a descriptive title (look at existing issues to get an idea of what works). The system will also search existing issues as you write – give it’s suggestions the once over in case you missed them in your search;
- Select a template from the description dropdown box. Is it a feature request (something new) or an issue? This will populate the write box with some handy hints for you to follow & expand upon.
- You’ll need to summarize the issue, the steps required to reproduce it, an explanation of what is currently happening and what you think should happen, plus details of the OF version, operating system, hardware & compiler etc.
- Where appropriate you can supply an example case that illustrates the issue, plus any relevant logs, output or images.
- Finally, if you can point to a possible fix in the code then that’s awesome, but optional.
If the details are all there (& it looks good in the preview tab) then go ahead & create your issue.
If in doubt, use the library of existing issues for reference. Browse a few to get a feel for the level of detail etc before finalising your submission.
Tips
Whilst putting this together I asked two of the OpenFOAM team if they had any tips on reporting issues (thanks Mark & Andy 🙏). They mostly mirrored the points above, but two particular details stood out to me:
- Your submission is welcome even if you’re not in a position to propose a solution. Just be sure to give them as much relevant information/context as possible to help them start their investigations.
- A small test case is super-helpful, but small is way smaller than you think. If you can capture your issue in < 100 cells then you’ll make testing potential fixes so much quicker. Take it as a challenge.
Do you have an issue?
Hopefully this has shed a little light on reporting OpenFOAM issues & maybe even reassured fellow non-developers that we can contribute to OpenFOAM in our own little way & that our contributions are welcome.
If you’ve noticed some unexpected behaviours / issues but avoided reporting them, then perhaps now’s the time?
You never know, your first issue might be the gateway to a bigger contribution or to an opportunity to help in other ways 🤞
If you need help with anything mentioned today (or in any other email) just drop me a note – I’m always happy to hear from you.
Until next week, stay safe,
