Repository navigation
joss: README contradicts paper and implemented functionality #82
Description
Location
README.md:126 and README.md:134; README "Haarpy functionality" section vs paper/paper.md summary && State of the field vs haarpy/__init__.py.
Concerns the origin/master (latest) branch.
[4]: README.md:152 vs README.md:159 and setup.py classifiers.
What
Three inconsistencies between the README, the paper, and the master branch code:
\begin{itemize}
- Symplectic averages.
README.md:126describes of the symplectic group: "Functionality to calculate averages will be added in the near term." Buthaar_integral_symplecticis implemented and exported (__init__.py), alongside this the paper claims symplectic moment calculations. - Circular-symplectic averages. Similarly to [1],
README.md:134repeats the phrase "near term", howeverhaar_integral_circular_symplecticis exported. - Free/quantum groups. The paper's Summary and State of the field claims "the quantum groups (free symmetric and free orthogonal)", and
haar_integral_free_symmetric&haar_integral_free_orthogonalare implemented however but the README functionality list does not mention this. - Version mismatch
README.md:152"Haarpy requires Python version 3.9 or later", butREADME.md:159(Compiling from source) says "Python >= 3.10", andsetup.pyclassifiers says 3.10–3.13. The 3.9 claim appears to be old.
REMARK: [3] cites the same issue and builds on #55.
Why
The "Documentation" criterion expects the README to accurately reflect functionality provided by the software and match claims provided in paper.md.
w.r.t [4]: The "Installation" criterion expects clear, correct dependency information.
Suggested Fix
Update the README to drop the two "near term" warnings cited to the user, and add a subsection documenting the free symmetric / free orthogonal (quantum-group) functions additionally fixing the version mismatch on documentation. Whence the documentation for the Quantum group functions are added as well; I will review and verify those clauses.
After fixing version mismatch, it would also help if you test using a CI matrix over 3.10-3.13 in your github ci (up to authors.) since I believe 3.10-3.13 is the main versions you are targeting.
Related to openjournals/joss-reviews/issues/11002
Activity
[-][JOSS Review] README contradicts paper and implemented functionality[/-][+]joss: README contradicts paper and implemented functionality[/+]trintlermint commentedon Aug 7, 2026
@yaniccd as you mentioned in #83:
I recommend it would be best you open a PR tackling this particular issue and apply the markdown formatter on
README.mdat the same time.I assume this is what you wanted to do already, but I just let you know.
Have a good summer! And great work on the other (joss) issues.
yaniccd commentedon Aug 7, 2026
Hi @trintlermint,
PR #100 should close this issue.
README.mdhas been passed through a markdown formatter. Once this PR as well as PR #95 and PR #96 are merged, all issues raised regarding the JOSS submission should be closed. I am currently waiting a final review from @nquesada. Thank you so much for your help regarding this submission!trintlermint commentedon Aug 7, 2026
Hi @yaniccd,
Looks great! The work you have put out looks great! I have skimmed through the README update as well and it looks fine to me. You may also close #55 upon merging the fixing PR #100 since it fixes issue part [3] highlighted in my original text.
Whence you have merged the corresponding PRs, please write a short descrption on the fixes done and highlight to the editor (danielskatz or oleksander) that all issues by reviewers have been closed in the orignal review thread.
Also, just as a good software development practice for future developments, I recommend to make the git commits more detailed such that any contributor realises what change a particular developer makes at what point and to avoid duplicating commit messages. An example of a good "convention" is the Conventional Commits 1.0 specification. This is just a recommendation, since you are listed publicly on pypl, it also helps users to understand what features, documentation changes, etc were changed when pulling newer versions of your package when they look at the git commit messages. You can choose to use to not use the convention, or just some parts -- I think its helpful!
Well, thats all from me! Good luck with the merging.
trintlermint commentedon Aug 7, 2026
I also recommend that #99 gets merged before full acceptance
yaniccd commentedon Aug 11, 2026
@trintlermint, I will write in the review thread that all issues raised have now been closed.
I just had a look at the Conventional Commits 1.0 and now realize that my commit messages are indeed not detailed enough. I will correct that from now on. Thank you for pointing it out!