[DNM][JOSS] JOSS paper

[valeriupredoi]

Description

Latest draft PDF: https://github.com/NCAS-CMS/pyfive/blob/joss_paper/paper.pdf

Summary

This is the PR that contains the JOSS paper we are writing; this is DNM (do not merge) since we don't want to have the paper in our code base, but it makes it easier to contribute to the paper via code review, and it shows the JOSS folks that we are writing the paper off an up to date main branch, that is tested and has coverage measured.

• the branch is here https://github.com/NCAS-CMS/pyfive/tree/joss_paper (ie this PR-ed branch)
• example explained (incl how to get references in) here https://joss.readthedocs.io/en/latest/example_paper.html
• (optional?) script to generate metadata for paper https://gist.github.com/arfon/478b2ed49e11f984d6fb

How to work on it

• checkout this joss_paper branch as per normal, make changes, commit and push
• at push, the PDF compiler Github Action will run, that will produce the paper PDF and commit it to this branch, as well as create a paper.zip Artifact that can be downloaded (that only contains the paper pdf)
• the latest draft PDF can be viewed here https://github.com/NCAS-CMS/pyfive/blob/joss_paper/paper.pdf
• the latest draft paper.zip artifact is available on the Action page, eg https://github.com/NCAS-CMS/pyfive/actions/runs/17856845646
• IMPORTANT since the bot pushes the latest draft here, you will always need to pull the latest branch locally ie do git pull origin joss_paper since you need to bring your HEAD to the latest state; if you don't, and get stuck at git conflicts, allow for merge with no rebase ie run git config pull.rebase false then pull again

Closes #94

Before you get started

• ☝ Create an issue to discuss what you are going to do

Checklist

• This pull request has a descriptive title and labels
• This pull request has a minimal description (most was discussed in the issue, but a two-liner description is still desirable)
• [ ] Unit tests have been added (if codecov test fails)
• [ ] Any changed dependencies have been added or removed correctly (if need be)
• [ ] If you are working on the documentation, please ensure the current build passes
• All tests pass

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.58%. Comparing base (85ba6aa) to head (dbc24f2).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #95   +/-   ##
=======================================
  Coverage   72.58%   72.58%           
=======================================
  Files          11       11           
  Lines        2499     2499           
  Branches      379      379           
=======================================
  Hits         1814     1814           
  Misses        583      583           
  Partials      102      102           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[valeriupredoi]

@bnlawrence had a very good point about running the JOSS converter on a draft, so I asked the JOSS folks at openjournals/joss#1456

[valeriupredoi]

@bnlawrence had a very good point about running the JOSS converter on a draft, so I asked the JOSS folks at openjournals/joss#1456

proves out there are multiple ways, described in the JOSS docs https://joss.readthedocs.io/en/latest/paper.html#checking-that-your-paper-compiles (duh!) - and the GHA one is perfect for us here, I'll implement it tomorrow 🥳

[Zeitsperre]

Hey all, the article is looking good!

I've left a bunch of comments around the wording of the article here. Many of these are just suggestions to make things more concise, but a few of my comments should be resolved. Pick and choose as you will!

Best, Trevor

[bnlawrence]

Thanks @Zeitsperre. I've taken on board most of your suggestions in one form or another - there were some good catches there - particularly in terms of specificity about when we were talking about the format itself.

[valeriupredoi]

folks, we are fully published, well done!! I even added a badge for the paper to our README https://github.com/NCAS-CMS/pyfive - what shall we do with this branch? I reckon we should keep it as-is for a while, just in case anything still needs be done at JOSS, then maybe just move the paper files to a dedicated dir and pop that onto main? Up to you 🍻