Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @igarizio, @mbdemoraes it looks like you're currently assigned to review this paper 🎉.

⭐ Important ⭐

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

👉 Check article proof 📄 👈

I have started the review as we have now 2 reviewers. But please note that with the special conditions these days, many of us are in complicated situations. There is no pressure to conduct the reviews right now, just do it if / when it's convenient. I will keep following and answer when needed.

👋 @mbdemoraes I think you clicked my checkboxes. I transferred them to your review 😁.

@igarizio I'm sorry! You are right, my mistake. Thank you for letting me know. 😅

The authors propose a python library to solve four "matching games" problems. I could locate the repository, install and run the examples from both README and documentation. The paper is well-written and introduces the field clearly and objectively. Also, the "Discussion" section in the documentation allows the reader to understand the subject in greater depth. Good job!

Some minor aspects that need revision on the documentation:

• There is a "How to" page that is empty;
• Under "Indice and Tables" on the home page, there is a "Search page" that is also empty;

Also, I have a few suggestions that I believe will improve this work:

• Remove the "code figure" from the paper. Although JOSS is a software-oriented journal, the paper is the place where you introduce motivations, theoretical and scientific aspects of your work. Software functionality should be addressed only on the documentation;

• Include on the documentation that for people with two python installations (versions 2 and 3+), they may have to use the command "python3" to install the package and run the examples, since in that case, the "python" command is the default for python2. It would be a command like this: "python3 -m pip install matching" and to run an example "python3 example.py". This is a common problem when you do not have a scientific python distribution (such as anaconda) installed. It may be obvious for experienced users but others may experience some difficulties;

• In the paper, the first paragraph of the "Statement of Need" section, the authors write that "Matching games have applications in a number of fields including social and market economics, wireless communication and education infrastructure". Although a practical application in education infrastructure is easily understandable given the examples itself (for instance, the student-allocation problem), applications in market economics and wireless communication are not so easily perceptible. If the authors can provide some specific applications under these fields, more researchers can understand the applicability of the library.

• On the "Get in contact!" section of README, the authors use "PRs" as an acronym for "Pull requests". I know it is a well-known abbreviation for GitHub users, but again, some readers may not understand. I suggest using the full text "Pull requests" to improve readability.

Thank you for the opportunity to review this work! Let me know when the revision has been made.

👋 Hi @daffidwilde. Thank you for submitting your paper!

The paper is well written and the code is clear, easy to use and properly documented (good job!). So far, I have only found some small issues:

• As @mbdemoraes mentioned, the “How to” page on the documentation is empty.
• In the setup.py file, I think you may be missing the hypothesis package (in “tests_require”). (The package is correctly listed everywhere else.) After installing it all tests pass. I should also mention that the coverage is perfect!
• I get a ValueError when running a StableMarriage game twice. I opened an issue with more details [ValueError when re-running a StableMarriage game daffidwilde/matching#80].

Opinion:

• While the “code figure” on the paper may look a little bulky, I do not think you need to remove it, as it highlights how easy it is to use your package (maybe you can remove the “>“ (?)).
  @mbdemoraes It is true that JOSS says not to include “software documentation such as API functionality” (link), but I think in this case, it is trying to show a strength of the package, not documenting it. What do you think? 👀
• On game.py, you mention that the Game class is just a “base class and is not intended for use other than inheritance”. Maybe you can use a metaclass to highlight that (so users get a nice warning on their IDE when subclassing it). This is just a suggestion, your code in completely fine without it.

@igarizio Thank you! I suggested that because I thought "code in the paper" was a restriction. But if it's not, you are certainly right, the image sure adds to the content. 😄

@mbdemoraes Perfect! As a reference, JOSS even has an example on how to add python code here, and also there are other accepted papers with code in them (for example this one).

Hello everyone,

Thank you so much for getting back with your reviews so swiftly. I've opened a number of PRs on the matching repository that address most of the points you've raised and I'd appreciate your feedback.

I will be adding to these tomorrow but I think things are looking pretty good thus far.

Thanks 👍

One thing I haven't yet changed that I'd like to discuss more is this point raised by @mbdemoraes:

Include on the documentation that for people with two python installations (versions 2 and 3+), they may have to use the command "python3" to install the package and run the examples, since in that case, the "python" command is the default for python2. It would be a command like this: "python3 -m pip install matching" and to run an example "python3 example.py". This is a common problem when you do not have a scientific python distribution (such as anaconda) installed. It may be obvious for experienced users but others may experience some difficulties;

When writing the documenation, we decided that since Python 2 is not supported in Matching (by the use of f-strings, for instance) that this was not necessary -- although I see why that could become an issue as you've highlighted. Having said that, since Python 2 has been officially sunsetted as of January 2020, I would prefer to avoid distinguishing between "Python" and "Python 3".

Perhaps adding this requirement to the setup.py and making it clearer (via a warning directive) in the docs would be sufficient? We can discuss this more on this PR if you'd like so as not to clutter this issue.

@daffidwilde I understand! Adding this requirement to the setup.py and/or making it clearer in the documentation would sure be sufficient. 👍

Fantastic! I'll get on that now.

👋 Hello all!

I've now completed making the changes requested here in Matching. The changes have been split amongst seven pull requests.

It'd be great if you could have a look at these changes whenever you get the chance.

Thanks again for all the suggestions and discussion 😄

@daffidwilde All the pull requests seem good to me. Thank you for making the suggested changes!
Let me know when you merge them.

@VivianePons I've made a new release on GitHub and the Zenodo archive is here

DOI is 10.5281/zenodo.3755304
Version is v1.3.0

Hi @daffidwilde : I need the metadata to exactly match the paper (title and author) thanks!

Oh yes, of course. I've sorted that now @VivianePons 👍

@whedon set 10.5281/zenodo.3755304 as doi

I'm sorry human, I don't understand that. You can see what commands I support by typing:

@whedon commands

@whedon set 1.3.0 as version

OK. 1.3.0 is the version.

@whedon set 10.5281/zenodo.3755304 as archive

OK. 10.5281/zenodo.3755304 is the archive.

Congratulations @daffidwilde for having your paper accepted at JOSS! thanks again to the reviewers @mbdemoraes and @igarizio for their great work

@whedon accept

👋 @openjournals/joss-eics, this paper is ready to be accepted and published.

Check final proof 👉 openjournals/joss-papers#1424

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#1424, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

@whedon accept deposit=true

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.02169 joss-papers#1425
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.02169
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? notify your editorial technical team...

@igarizio, @mbdemoraes - many thanks for your reviews here and to @VivianePons for editing this submission ✨

@daffidwilde - your paper is now accepted into JOSS ⚡🚀💥

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://joss.theoj.org/papers/10.21105/joss.02169/status.svg)](https://doi.org/10.21105/joss.02169)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.02169">
  <img src="https://joss.theoj.org/papers/10.21105/joss.02169/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.02169/status.svg
   :target: https://doi.org/10.21105/joss.02169

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: https://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss