Updated citation

[jonseddon]

🚀 Pull Request

Description

A documentation tweak to update the citation to a more recent version (it's currently using version 1.2) and to better use DOIs.

Implements #4679

[trexfeathers]

I like this. Anyone in @SciTools/iris-devs have expertise in citations, and would be happy to take a look?

[bouweandela]

It would be nice to make the package easily citable from GitHub by adding a citation file, you can find more information about adding that here: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files. That will add a little button to GitHub where you can download the bibtex file.

[jonseddon]

#5118 added to cover @bouweandela's suggestion about the citation file. I won't add that in this PR to keep everything separate.

[stephenworsley]

This looks great in principle, It would be good to add instructions for how/when to update this in future releases to the developer docs. (somewhere in here, probably as part of the post release steps https://github.com/SciTools/iris/blob/main/docs/src/developers_guide/release.rst)

[jonseddon]

@stephenworsley note added to https://github.com/SciTools/iris/blob/main/docs/src/developers_guide/release.rst

I guess that I probably need to rebase as I've done "git pull upstream main" several times. Please let me know if a rebase is required - I'm not used to working on a Git repo that's so active.

[pp-mo]

I probably need to rebase as I've done "git pull upstream main" several times.

I think on the contrary, if you've been updating from main then a rebase is not required.
You definitely don't want to mix the two, as when code changes from main are included in the development commits on your branch (i.e. the ones which aren't merges from the target), that will usually cause conflicts when trying to merge back.

The tests panel here shows that it is currently OK to merge -- i.e. has no conflicts with the current main branch. If there was a problem, it would say there that there are conflicts (and merge button will be disabled).

Rebasing is another way of fixing merge conflicts, whereby git re-bases all your commits onto the latest in the target branch.
It effectively re-plays your change commits, one at a time, starting from the current target and merging each change into it.
At each step, if it fails to automate that rewrite, then you must manually resolving conflicts (just like a merge).
The benefit of this approach is that the history on the the PR branch is much simpler, not including merges back from the target, and so you can easily see "what I changed between point A and point B of this development process" without changes drawn from main complicating the difference.
It's great when it works! But when it goes wrong, it's usually easier to squash all your commits into one and resolve all conflicts in one go -- which of course destroys the sequence, and may not be good if that makes the changes really hard to understand.

It's also worth noting that some people seem to hate rebase, because it automatically re-writes your changes so that they are now "magically" ok -- i.e. will merge without conflict. Yet, you didn't do that, and in principle you should carefully review each new commit + check it makes sense and you are happy to "sign it off".
However, in my opinion this is really no different from any automatic merge : whenever it says "merges with no conflicts", that means it is making automated changes to what you wrote!

Bit of a rant. HTH ?!?

[jonseddon]

@pp-mo Thanks for the rant and great explanation. That all makes sense now.