add citation file and validating GHA (#5483)

* add citation file and validating GHA

* adding the CITATION.cff to the manifest file

* added - name: to CITATION.cff

* some of the requested changes

* updating the citation page and adding whatsnew entry

* adding repository link

* rewording and adding more links

.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"

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"

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

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/

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
 ===========