Repository: SciTools/iris (language: python)

Issue:
Adding a CITATION.cff file
## 🚀 Pull Request

### Description
<!-- Provide a clear description about your awesome pull request -->
<!-- Tell us all about your new feature, improvement, or bug fix -->

I have written the CITATION.cff file for Iris using the information from the [citation page](https://scitools-iris.readthedocs.io/en/latest/userguide/citation.html) of the documentation.

This pull request is a WIP and will require changes based on the answers to some questions that I have below.

resolves #5118

### Questions for @SciTools/iris-devs

1. In the documentation, currently the BibTeX entry begins with @manual tag. When looking through the old PR's #389 and #5116, I cannot find any consideration being given to the @software tag even though to me this seems like the most natural fit. Could you let me know the reasons behind this choice, and I can update the CITATION.cff to reflect @manual if you feel that is still the best fit.

2. With the existence of this file, what should become of the existing citation page of the documentation?
- My thought is that the documentation should in some way link to or reference the github to obtain the references rather than also manually listing them out in the documentation as currently it would be a duplication and so both would need to be maintained.

3. Where would be the best place for this in the 'What's New' section of the documentation?
- 3.5 Given the potential overhaul of the citation page in the documentation what should happen to the existing entry in the documentation section of the 'What's New' "3. [@jonseddon](https://github.com/jonseddon) updated the citation to a more recent version of Iris. ([PR #5116](https://github.com/SciTools/iris/pull/5116))".

---
[Consult Iris pull request check list]( https://scitools-iris.readthedocs.io/en/latest/developers_guide/contributing_pull_request_checklist.html)

Possible citation updates -- not clear whether appropriate.
I'm unclear whether these changes folllow the correct form, but I  suspect anyway that the existing format where it says "doi = {10.5281/zenodo.7386117}" is possibly wrong : this is not a complete valid url.

~TBD~
**UPDATE** it is a doi, should not be a url (!)
Make it clearer / easier to find how to cite Iris
## 📚 Documentation
<!-- See https://scitools-iris.readthedocs.io/en/latest/ -->
<!-- Describe the issue or provide a suggestion for improving the Iris documentation -->
It's currently pretty hard to work out how to cite Iris (and not in the docs). I think the only indication is that we have a Zenodo tag on our GitHub README. I'd suggest improving this.

Examples from elsewhere (both what they use and how you find out about it):
- Pandas use Zenodo and a paper: https://pandas.pydata.org/about/citing.html
- Numpy have a paper: https://numpy.org/citing-numpy/
- SciPy have a paper: https://scipy.org/citing-scipy/
- Matplotlib have a paper and a Zenodo DOI (Digital Object Identifier): https://matplotlib.org/stable/users/project/citing.html
Add a citation file
## ✨ Feature Request
A citation file  (CITATION.cff in the root of the repository) would contain information on how to cite Iris; GitHub would add a box explaining how to cite Iris and there is integration with Zenodo too. There's more information in https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files. Much of the information to create the file is in the Iris user guide at https://scitools-iris.readthedocs.io/en/latest/userguide/citation.html.

## Motivation
This is a quick win, with minimal effort and may help to gather evidence of the use of Iris.

## Additional context
This was first mentioned in PR #5116. 



Discussion / hints:
To avoid mistakes in the citation file, I would recommend setting up a [GitHub action to validate the citation file](https://github.com/citation-file-format/cffconvert-github-action).
I agree that we should definetly be referencing the people rather than just the organisation but I think doing so with all of the contributors would make the citation way too long and unwieldy, but I also do not feel in a position to decide who is or isn't deserving of the citation. Most other packages use a prefered citation of a paper or article of some sort to avoid this problem, but even if we decide to do that, its beyond the scope of this task. Therefore I think a decision is required on how to proceed.
How about “Iris contributors”, to match the copyright notices?  Pandas has [The pandas development team](https://github.com/pandas-dev/pandas/blob/main/CITATION.cff).
Oops, made a mistake rebasing it and it added all of the other commits. I will re make the pull request with the changes originally looked at.

We have a docs page for this but I expect it could do with an overhaul.  

https://scitools-iris.readthedocs.io/en/latest/userguide/citation.html#citing-iris
Odd - when I search the docs for the word "cite" I don't get that page, only a very old what's new entry (which does link to that page). Maybe it's just a matter of cross-linking a bit better and updating that page
In order to maintain a backlog of relevant issues, we automatically label them as stale after 500 days of inactivity.

If this issue is still important to you, then please comment on this issue and the stale label will be removed.

Otherwise this issue will be automatically closed in 28 days time.
@HGWright any thoughts on the status of this? I've lost track if we've already done the "make it clearer / easier" step
@trexfeathers Thanks for the reminder I had forgoten about this. It still needs work to finish #5161.


Fix patch:
diff --git a/.github/workflows/ci-citation.yml b/.github/workflows/ci-citation.yml
new file mode 100644
index 0000000000..99cced758b
--- /dev/null
+++ b/.github/workflows/ci-citation.yml
@@ -0,0 +1,30 @@
+name: ci-citation
+
+on:
+  pull_request:
+    paths:
+      - "CITATION.cff"
+
+  push:
+    paths:
+      - "CITATION.cff"
+
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: "validate"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: "check CITATION.cff"
+        uses: citation-file-format/cffconvert-github-action@4cf11baa70a673bfdf9dad0acc7ee33b3f4b6084
+        with:
+          args: "--validate"
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 0000000000..c3fcdd26d5
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If Iris played an important part in your research then please add us to your reference list by using the references below."
+title: "Iris"
+keywords:
+  - "cf-metadata"
+  - "data-analysis"
+  - "earth-science"
+  - "grib"
+  - "netcdf"
+  - "meteorology"
+  - "oceanography"
+  - "space-weather"
+  - "ugrid"
+  - "visualisation"
+authors:
+    - name: "Iris contributors"
+abstract: "A powerful, format-agnostic, and community-driven Python package for analysing and visualising Earth science data"
+license: "BSD-3-Clause"
+license-url: "https://spdx.org/licenses/BSD-3-Clause.html"
+doi: "10.5281/zenodo.595182"
+url: "http://scitools.org.uk/"
+repository-code: "https://github.com/SciTools/iris"
+type: "software"
diff --git a/MANIFEST.in b/MANIFEST.in
index 28eaf30baa..e594303d8f 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -18,6 +18,9 @@ exclude .ruff.toml
 exclude CHANGES
 exclude CODE_OF_CONDUCT.md
 exclude codecov.yml
+include COPYING
+include COPYING.LESSER
+include CITATION.cff
 include LICENSE
 exclude Makefile
 exclude noxfile.py
diff --git a/docs/src/userguide/citation.rst b/docs/src/userguide/citation.rst
index 7169ca3072..d0496f4876 100644
--- a/docs/src/userguide/citation.rst
+++ b/docs/src/userguide/citation.rst
@@ -5,53 +5,16 @@ Citing Iris
 ===========
 
 If Iris played an important part in your research then please add us to your
-reference list by using one of the recommendations below.
+reference list by using the recommendations below.
 
-************
-BibTeX Entry
-************
+Iris can be cited directly from the `GitHub repository <https://github.com/SciTools/iris>`_
+, for more information including where to find the citation on the repo please
+see the `GitHub documentation`_.
 
-For example::
+The Iris citation does not contain the version of the software used. We
+recommend that you use the version number of the release you used, and the
+commit hash if you checked out a unreleased version of Iris. This will allow
+others to reproduce the environment that you worked in. You can see what a
+citation should look like for a particular version of Iris, on the `GitHub documentation`_.
 
- @manual{Iris,
- author = {{Met Office}},
- title = {Iris: A powerful, format-agnostic, and community-driven Python package for analysing and visualising Earth science data},
- edition = {v3.7},
- year = {2010 - 2023},
- address = {Exeter, Devon},
- url = {https://github.com/SciTools/iris},
- doi = {10.5281/zenodo.8305232}
- }
-
-
-*******************
-Downloaded Software
-*******************
-
-Suggested format::
-
- ProductName. Version. ReleaseDate. Publisher. Location. DOIorURL. DownloadDate.
-
-For example::
-
- Iris. v3.7. 31-Aug-2023. Met Office. UK. https://doi.org/10.5281/zenodo.8305232 22-12-2022
-
-
-********************
-Checked Out Software
-********************
-
-Suggested format::
-
- ProductName. Publisher. URL. CheckoutDate. RepositorySpecificCheckoutInformation.
-
-For example::
-
- Iris. Met Office. https://github.com/SciTools/iris.git 31-08-2023
-
-.. _How to cite and describe software: https://software.ac.uk/how-cite-software
-
-
-Reference: [Jackson]_.
-
-.. [Jackson] Jackson, M. 2012. `How to cite and describe software`_. Accessed 06-03-2013.
+.. _GitHub documentation: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files/


Test patch:
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
index 13e3b9e4ea..f73d6b0090 100644
--- a/docs/src/whatsnew/latest.rst
+++ b/docs/src/whatsnew/latest.rst
@@ -26,6 +26,10 @@ This document explains the changes made to Iris for this release
 
 #. `@lbdreyer`_ relicensed Iris from LGPL-3 to BSD-3. (:pull: `5577`)
 
+#. `@HGWright`_, `@bjlittle`_ and `@trexfeathers`_ (reviewers) added a
+   CITATION.cff file to Iris and updated the :ref:`citation documentation <Citing_Iris>`
+   , to help users cite Iris in their work. (:pull:`5483`)
+
 
 ✨ Features
 ===========