Peer Review - Nour Shawky

[nourshawk]

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• As the reviewer, I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in the README file.
• Installation instructions: for the development version of the package and any non-standard dependencies in README.
• Short quickstart tutorials demonstrating significant functionality that successfully runs locally.
• Function Documentation: for all user-facing functions.
• Examples for all user-facing functions.
• Community guidelines including contribution guidelines in the README or CONTRIBUTING.
• Metadata including author(s), author e-mail(s), a URL, and any other relevant metadata, for example, in a pyproject.toml file or elsewhere.

Readme file requirements
The package meets the readme requirements below:

• Package has a README.md file in the root directory.

The README should include, from top to bottom:

• The package name
• Badges for:
  • Continuous integration and test coverage,
  • Docs building (if you have a documentation website),
  • Python versions supported,
  • Current package version (on PyPI / Conda).

NOTE: If the README has many more badges, you might want to consider using a table for badges: see this example. Such a table should be wider than high. A badge for pyOpenSci peer review will be provided when the package is accepted.

• Short description of package goals.
• Package installation instructions
• Any additional setup required to use the package (authentication tokens, etc.)
• Descriptive links to all vignettes. If the package is small, there may only be a need for one vignette which could be placed in the README.md file.
  • Brief demonstration of package usage (as it makes sense - links to vignettes could also suffice here if package description is clear)
• Link to your documentation website.
• If applicable, how the package compares to other similar packages and/or how it relates to other packages in the scientific ecosystem.
• Citation information

Usability

Reviewers are encouraged to submit suggestions (or pull requests) that will improve the usability of the package as a whole.
The package structure should follow the general community best practices. In general, please consider whether:

• Package documentation is clear and easy to find and use.
• The need for the package is clear
• All functions have documentation and associated examples for use
• The package is easy to install

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.
• Performance: Any performance claims of the software been confirmed.
• Automated tests:
  • All tests pass on the reviewer's local machine for the package version submitted by the author. Ideally this should be a tagged version making it easy for reviewers to install.
  • Tests cover essential functions of the package and a reasonable range of inputs and conditions.
• Continuous Integration: Has continuous integration setup (We suggest using Github actions but any CI platform is acceptable for review)
• Packaging guidelines: The package conforms to the pyOpenSci packaging guidelines.
  A few notable highlights to look at:
  • Package supports modern versions of Python and not End of life versions.
  • Code format is standard throughout package and follows PEP 8 guidelines (CI tests for linting pass)

For packages also submitting to JOSS

• The package has an obvious research application according to JOSS's definition in their submission requirements.

Note: Be sure to check this carefully, as JOSS's submission requirements and scope differ from pyOpenSci's in terms of what types of packages are accepted.

The package contains a paper.md matching JOSS's requirements with:

• A short summary describing the high-level functionality of the software
• Authors: A list of authors with their affiliations
• A statement of need clearly stating problems the software is designed to solve and its target audience.
• References: With DOIs for all those that have one (e.g. papers, datasets, software).

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 1

---

Review Comments

Really cool package, with well-written functions and tests. To strengthen the package structure and functionality further, please consider some of the following additions/changes:

• Your deployment workflow is missing steps to publish your package to Test PyPI.
• The installation instruction in the readme, specifically pip install sudoku_validation doesn't run as the package is not published on PyPI. I would recommend setting up your CD/deployment workflow file so that it automatically publishes your package to Test PyPI, or PyPI if you prefer, and then you should update your installation command accordingly!
• One minor fix in the readme: 'cd sudoku_validationshould be changed tocd Sudoku_Validation` to match your package name.
• Similarly, conda activate sudoku-validation should be conda activate sudoku_validation.
• I was able to activate the environment and run all the tests, with everything passing, which was great!
• Documentation is clearly linked in the readme and i was also able to build it locally using the developer commands. The home page of the documentation lists good, clear example use cases of the functions.
• However, you might consider including the full docstring breakdown in the 'API reference' page of your website, that lists the function parameters, what it returns, errors it could raise etc. This could be configured using quartodoc instead of manually writing them into your qmd files.
• For organization and clarity purposes, it would be nice to keep track of your feature additions/fixes in the Changelog file.

Overall, great work!!

[Olytics]

Thank you for your review @nourshawk . We have addressed the API reference page in the documentation website, which is linked in #87. Other changes that have been made are also linked. We will review and implement your other suggestions in the future, and they are currently in our backlog.

Thank you for your time!