JOSS review thread

[andrewheiss]

Hello! I'm reviewing this package/paper for JOSS (openjournals/joss-reviews#7477), and following their recommendation, I'll leave comments and suggestions as comments here.

[andrewheiss]

Super minor thing (and I can't find the LaTeX file that generates the paper in this repo—it likely lives elsewhere): Figures 1 and 2 in the paper aren't vector based. This is fine for Figure 1 since it uses a high enough resolution that it looks okay, but Figure 2 appears quite pixelated (almost unreadable) when printed. Including SVGs or PDFs in the paper manuscript (or higher resolution PNGs) would be helpful.

[andrewheiss]

Everything installed just fine for me both via pip and through poetry—it was my first time using poetry and it was really neat that it automatically created a virtualenv and installed everything

I did get an error initially, since my system python is 3.13.1, and the project settings look for less than 3.13:

VoteKit/pyproject.toml

Line 9 in 1d739fe

python = "^3.9,<3.13"

…but poetry ended up automatically installing a 3.9 virtualenv for me. Perhaps allowing >3.13 could be helpful

[andrewheiss]

The current repo uses Sphinx to build https://votekit.readthedocs.io/en/latest/, which seems to be the actual documentation. It uses the comprehensive ipynbs in https://github.com/mggg/VoteKit/tree/main/notebooks to provide a helpful tutorial, and for my part, running those notebooks interactively on my own was the best way for me to get familiar with the package and its functionality and output. These are great and should be kept as the main documentation tutorial.

There's a link to an older, less-organized and less-polished version of the documentation (https://mggg.github.io/VoteKit/) that I accidentally used as my initial entry to the documentation and it took a while to figure out why it didn't match what was in the current repo:

VoteKit/README.md

Line 22 in 1d739fe

A simple example of how to use VoteKit to load, clean, and run an election using real [data](https://vote.minneapolismn.gov/results-data/election-results/2013/mayor/) taken from the 2013 Minneapolis Mayoral election. For a more comprehensive walkthrough, see the [documentation](https://mggg.github.io/VoteKit/).

[andrewheiss]

JOSS recommends having clear contributor guidelines:

Community guidelines: Are there clear guidelines for third parties wishing to 1. Contribute to the software 2. Report issues or problems with the software 3. Seek support

The project currently has a code of conduct, and the README states that "bug reports and feature requests, as well as contributions, are welcome", but it doesn't provide guidelines for how to do that (like issue templates, recommendations for contributors, style preferences, etc.)

It might be helpful to include a CONTRIBUTING.md file—see https://github.com/jessesquires/.github/blob/main/CONTRIBUTING.md for a good generic one that I've adapted from several times, or this shorter R-specific one, or GitHub's official example guide for examples.

[cdonnay]

Thank you for the super detailed feedback! We really appreciate it.