[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 🥳

[valeriupredoi]

@bnlawrence this branch is now fully up to date with main; I am looking at the paper now, not reading it (since I read it last week), just looking to see if all the bits are in place etc. When do you want to submit?

[valeriupredoi]

So I'm pasting the submission criteria here, taken from https://joss.readthedocs.io/en/latest/submitting.html:

• Make your software available in an open repository (GitHub, Bitbucket, etc.) and include an OSI approved open source license.
• Make sure that the software complies with the JOSS review criteria. In particular, your software should be full-featured, well-documented, and contain procedures (such as automated tests) for checking correctness.
• Write a short paper in Markdown format using paper.md as file name, including a title, summary, author names, affiliations, and key references. See our example paper to follow the correct format.
• (Optional) create a metadata file describing your software and include it in your repository. We provide a script that automates the generation of this metadata.

@bnlawrence the short submission form is here and needs a login, if you'd like to do that perfect, if not I can create a new account for meself 🍺

[bnlawrence]

I have submitted this to JOSS. I guess when the review is done we kill this as a pull request, but keep the branch.

[valeriupredoi]

I have submitted this to JOSS. I guess when the review is done we kill this as a pull request, but keep the branch.

legend, cheers, Bryan! I should guess the review and changes from it will happen in a fork of this at JOSS? Yes, we should update the files with the final versions, after review, then I'll close the PR without merge but will deffo keep the branch, and I'll protect it from deletion