authorship, citation, and attribution policies

ATTRIBUTION.rst

@@ -1,50 +1,113 @@
 .. _attribution_ref_label:
 
-Attribution Guidelines
-======================
+Recognizing Contributions
+=========================
 
-We are extremely grateful to everyone who has contributed to the success of the icepyx community, whether through direct contributions to or feedback about icepyx or as developers or maintainers of complimentary resources that are included within the icepyx ecosystem. This document outlines our goals to give appropriate attribution to all contributors to icepyx in ways that are fair and diverse and supportive of professional goals. To do so, we define broadly *contributions* as:
+We are extremely grateful to everyone who has contributed to the success of the icepyx community and software.
+This document outlines our goals to give appropriate attribution to all contributors to icepyx in ways that are fair and diverse and supportive of professional goals. 
+We define *contributions* broadly as:
 
-    Efforts towards achieving icepyx's goals, including writing code, tests, or documentation,
-    development of example workflows, development, significant contributions, or maintenance of
-    a tailored package that broadens the functionality of icepyx, feedback and suggestions,
-    community building, etc.
+    Efforts towards achieving icepyx's goals, including (1) writing code, tests, or documentation,
+    (2) development of example workflows, (3) development, significant contributions, or maintenance of
+    a tailored package that broadens the functionality of icepyx, (4) feedback and suggestions,
+    (5) community building, (6) etc.
+
+We recognize contributions in the following ways.
+
+  **Note**: These policies are not set in stone and may be changed to
+  accommodate the growth of the project or the preferences of the community.
 
-We use the terms "contributors", "developers", and "authors" interchangeably. We will recognize contributions in the following ways.
 
 Contributors List
 -----------------
-Anyone who has contributed a pull request to icepyx is welcome to add themselves to the ``CONTRIBUTORS.rst`` file located in the top level directory; the file is packaged and distributed with icepyx. This process is optional, but is the easiest way for us to say "thank you" to everyone who has helped this project.
+
+This project follows the `all-contributors <https://github.com/all-contributors/all-contributors>`_ specification. 
+When you contribute to icepyx for the first time or in a new way, you or a maintainer can use the `All Contributors bot
+to open a PR <https://allcontributors.org/docs/en/bot/usage>`_` to recognize your contribution.
+Comment on an existing PR with `@all-contributors please add @<username> for <contributions>`.
+This will add you (or your new contribution type) to the ``CONTRIBUTORS.rst`` file located in the top level directory; 
+the file is packaged and distributed with icepyx, so each release has a record of contributors and their contribution types.
+
+
+Changelog
+---------
+
+Each release includes a changelog of updates.
+Everyone who has made a commit since the last release is listed, with new contributors indicated.
+This list is automatically generated using a Sphinx extension; where available, full names are used.
+If the user's full name is not available on GitHub, their GitHub handle is used.
 
 
 Example Workflows
 -----------------
-Many of the example workflows included within icepyx were developed by individuals or small teams for educational or research purposes. We encourage example developers to provide proper recognition for these efforts both within the notebook itself and by adding contributors to the `Contributors List`_ for attribution as describered herein.
 
+Many of the example workflows included within icepyx were developed by individuals or small teams for educational or research purposes. 
+We encourage example developers to provide proper recognition for these efforts both within the notebook itself and 
+by adding contributors to the `Contributors List`_ for attribution as describered herein.
 
-Version Release on Zenodo
--------------------------
-When new releases of icepyx are archived on Zenodo, anyone who has contributed to icepyx will be invited to be an author. The list of potential authors will be generated using the `Contributors List`. Thus, if you have contributed to icepyx and would like to be included as an author, you *must* add your full name, affiliation ("Unaffiliated" is acceptable), and ORCID (optional) to ``CONTRIBUTORS.rst``.
 
-Author order will be determined based on co-author discussion during preparation of the version release, led by one or more of the members of the lead development team (Anthony Arendt, Lindsey Heagy, Fernando Perez, Jessica Scheick). Metrics for guiding the determination of author order will include the number of commits made to the repository (``git shortlog -sne``) and active engagement on GitHub (e.g. through issues and pull requests) and Discourse. Author order may also be modified on a case-by-case basis by consensus of the lead development team and top contributors.
+Version Releases on Zenodo
+--------------------------
+
+Each new release of icepyx is `archived on Zenodo <https://zenodo.org/record/7754482>`_.
 
-If you do not wish to be included in the author list for Zenodo version releases, please add a note (e.g. "do not include in Zenodo") to your entry.
+Following the collaborative approach of `The Turing Way <https://the-turing-way.netlify.app/community-handbook/acknowledgement/acknowledgement-members.html>_`,
+we aim to encourage community leadership and shared ownership of icepyx.
+To this end, beginning with version 0.6.4 (the full adoption of the all-contributors specification)
+we collectively represent the icepyx authors in citations (including Zenodo releases) as "The icepyx Developers".
 
+As described above, a complete list of contributors and their contribution types is available via the `Contributors List`_.
 
-Scientific Publications (Papers)
---------------------------------
+  ** A note about releases <v0.6.4: Prior version releases adhere to authorship guidelines in place at the time, 
+  listing individual contributors who had manually added their names to `CONTRIBUTORS.rst`.
+  Authorship order was alphebetical by last name, except in cases where
+  a substantial contribution was made by one or more contributors to a given release. **
 
-Authorship on scientific papers currently constitutes an important metric for assessing scientific merit and contribution and is often directly linked to career advancement. We aim to write academic papers for our software and its uses. Ideally, we will publish on an early version of the software and subsequently on major releases, use cases, or to advance the causes of open-source software and open science. To be eligible for authorship on scientific papers, contributors must:
 
-  1. Contribute to the development (including code, documentation, and examples) of icepyx. Substantial non-code contributions constitute eligibility for authorship.
-  2. Add themself to the `Contributors List`_.
-  3. Contribute ideas, participate in authorship discussions (see next paragraph), write, read, and review the manuscript in a timely manner, and provide feedback (acknowledgement of review is sufficient, but we'd prefer more).
+Peer-Reviewed Publications (Papers)
+-----------------------------------
 
-Author order will be determined based on co-author discussion, led by the lead author, during the initial planning stages of manuscript preparation (i.e. as soon as an idea matures into a potential manuscript and before writing begins). Authorship will continue to be evaluated throughout the manuscript preparation process. Discussions will consider authorship norms (e.g. How does author order convey participation and prestige? How critical is first authorship to career advancement for each member of the team? Do an individual's contributions meet authorship criteria or are they more suited to acknowledgements?). Author order determination will also consider metrics such as the number of commits since the last major release with an associated paper (``git shortlog vX.0.0...HEAD -sne``), contributions that do not have associated commits, and contributions to the preparation of the manuscript.
+We will occasionally prepare manuscripts describing our software and its uses for submission to peer-reviewed journals. 
+These efforts are typically "in addition to" contributions made directly to icepyx (community or repository) and 
+thus may have specific author lists.
+To be eligible for authorship on a peer-reviewed publication, contributors must:
 
+  1. Contribute to the development (including code, documentation, and examples) of icepyx. 
+  Substantial non-code contributions may constitute eligibility for authorship.
+  2. Contribute ideas, participate in authorship discussions (see next paragraph), write, read, and review the manuscript 
+  in a timely manner, and provide feedback (acknowledgement of review is sufficient, but we'd prefer more).
 
+Author order will be determined based on co-author discussion, led by the publication preparation leader, ideally during the initial 
+planning stages of manuscript preparation (i.e. as soon as an idea matures into a potential manuscript and before writing begins). 
+Authorship will continue to be evaluated throughout the manuscript preparation process. 
+Discussions will consider authorship norms (e.g. How does author order convey participation and prestige? 
+How critical is first authorship to career advancement for each member of the team? 
+Do an individual's contributions meet authorship criteria or are they more suited to acknowledgements?). 
+Author order determination may also consider metrics such as the number of commits since the last major release 
+with an associated paper (``git shortlog vX.0.0...HEAD -sne``), contributions that do not have associated commits, 
+and contributions to the preparation of the manuscript.
 
-    Disclaimer: These policies are not permanent or fixed and may change to accomodate community growth,
-    best practices, and feedback.
 
-Copyright notice: This document was inspired by the `authorship guidelines <https://github.com/fatiando/contributing/blob/master/AUTHORSHIP.md>`_ provided by `Fatiando a Terra <https://github.com/fatiando>`_ and encourages potential co-authors to consider the resources provided by the `NASA High Mountain Asia Team (HiMAT) <https://highmountainasia.github.io/team-collaboration/authorship/>`_.
+Motivation and References
+-------------------------
+
+Concepts and models of attribution, credit, contribution, and authorship can vary across time, application, and communities.
+`FORCE11 <https://force11.org/>_` has an entire `Attribution Working Group <https://force11.org/groups/attribution-working-group/>_` dedicated to working on attribution for research products.
+`URSSI <https://urssi.us/>_` hosted a workshop in 2019 (`report <https://urssi.us/blog/2019/03/24/report-from-urssi-workshop-on-software-credit-citation-and-metrics/>_`) 
+to identify core issues and propose solutions to challenges around software credit.
+For software, current best practices (`e.g. <https://arxiv.org/pdf/2012.13117.pdf>_`) emphasize the importance of having a document
+such as this one to describe an individual community's policies for credit, authorship, and attribution.
+This document is an effort to describe icepyx's policies, with an awareness that they may change 
+to accomodate community growth, best practices, and feedback.
+
+We do not attempt to identify contribution levels through the number of commits made to the repository (e.g. ``git shortlog -sne``)
+or active engagement on GitHub (e.g. through issues, discussions, and pull requests) and Discourse.
+The latter is difficult to quantify, and the use of squash merges into the development branch can mask the relative complexity 
+of various contributions and does not necessarily capture significant conceptual contributions.
+
+
+Copyright notice: Preparation of this document and our credit policies was inspired in part by these `authorship guidelines <https://github.com/fatiando/contributing/blob/master/AUTHORSHIP.md>`_ provided by `Fatiando a Terra <https://github.com/fatiando>`_ 
+and `The Turing Way <https://the-turing-way.netlify.app/community-handbook/acknowledgement/acknowledgement-members.html>`_.
+We encourage potential contributors to consider the resources provided by the `NASA High Mountain Asia Team (HiMAT) <https://highmountainasia.github.io/team-collaboration/authorship/>`_
+and established or emerging best practices in their community.
+Please get in touch if you would like to discuss updates to this contribution recognition policy.

CITATION.cff

@@ -0,0 +1,35 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: icepyx
+message: >-
+  If you use this software, please cite the software version
+  you used by its version-specific DOI.
+  The DOI for each version is available on Zenodo (link below).
+type: software
+authors:
+  - name: The icepyx Developers
+repository-code: 'https://github.com/icesat2py/icepyx'
+url: 'https://icepyx.readthedocs.io/en/latest/'
+repository: 'https://zenodo.org/record/7729175'
+repository-artifact: 'https://anaconda.org/conda-forge/icepyx'
+abstract: >-
+  icepyx is both a software library and a community composed
+  of ICESat-2 data users, developers, and the scientific
+  community. We are working together to develop a shared
+  library of resources - including existing resources, new
+  code, tutorials, and use-cases/examples - that simplify
+  the process of querying, obtaining, analyzing, and
+  manipulating ICESat-2 datasets to enable scientific
+  discovery.
+keywords:
+  - ICESat-2
+  - Python
+  - open science
+  - NASA
+license: BSD-3-Clause
+identifiers:
+  - description: "All archived versions of icepyx."
+    type: doi
+    value: 10.5281/zenodo.7729175

CITATION.rst

@@ -6,33 +6,50 @@ Citing icepyx
 icepyx
 ------
 
-This community and software is developed with the goal of supporting science applications. Thus, our contributors (including those who have developed the packages used within icepyx) and maintainers justify their efforts and demonstrate the impact of their work through citations.
+This community and software is developed with the goal of supporting science applications.
+Thus, our contributors (including those who have developed the packages used within icepyx) 
+and maintainers justify their efforts and demonstrate the impact of their work through citations.
+
+If you have used icepyx in your work, please consider citing our library.
+We encourage you to use a version-specific citation and DOI (available from `Zenodo <https://zenodo.org/record/7754482>`_)
+to improve reproducibility and let users know the state of the software at the time of your analysis.
+
+A non-versioned citation of icepyx:
+    icepyx Developers, (2023). icepyx: Python tools for obtaining and working with ICESat-2 data.
+    Zenodo. https://doi.org/10.5281/zenodo.7754482
+
 
-If you have used icepyx in your work, please consider citing our library:
-    Scheick, J. *et al.*, (2019). icepyx: Python tools for obtaining and working with ICESat-2 data.
-    https://github.com/icesat2py/icepyx.
-
 A bibtex version for users working in Latex::
 
-    @Misc{icepyx,
+  @Misc{icepyx,
   author =    {Scheick, Jessica and others},
   organization = {icesat2py},
   title =     {{icepyx: Python} tools for obtaining and working with {ICESat-2} data},
-  year =      {2019--},
-  url = "https://github.com/icesat2py/icepyx"
-    }
+  year =      {2023},
+  doi = "https://doi.org/10.5281/zenodo.7754482",
+  publisher = {Zenodo},
+  url = "https://github.com/icesat2py/icepyx",
+  }
 
+For more information on the "icepyx Developers", please see our `Attribution Guidelines <https://icepyx.readthedocs.io/en/latest/contributing/attribution_link.html>`_.
+See our docs for a `full list of contributors <https://icepyx.readthedocs.io/en/latest/contributing/contributors_link.html>`_ and their contribution types.
 
 icepyx Dependencies
---------------------------
-If you have used one of the included packages to extend your data analysis capabilities within icepyx, please consider additionally citing that work, because it represents an independent software contribution to the open-source community. `SciPy <https://www.scipy.org/index.html>`_ provides a `helpful resource <https://www.scipy.org/citing.html>`_ for citing packages within the SciPy ecosystem (including Matplotlib, NumPy, pandas, and SciPy). Links to citation information for other commonly used packages are below.
+-------------------
+If you have used one of the included packages to extend your data analysis capabilities within icepyx, 
+please consider additionally citing that work, because it represents an independent software contribution to the open-source community. 
+`SciPy <https://www.scipy.org/index.html>`_ provides a `helpful resource <https://www.scipy.org/citing.html>`_ for citing 
+packages within the SciPy ecosystem (including Matplotlib, NumPy, pandas, and SciPy). 
+Links to citation information for other commonly used packages are below.
 
 - `fiona <https://github.com/Toblerity/Fiona/blob/master/CITATION.txt>`_
 - `GeoPandas <https://github.com/geopandas/geopandas/issues/812>`_
 - `Pangeo <https://github.com/pangeo-data/pangeo/issues/651>`_
 - `shapely <https://github.com/Toblerity/Shapely/blob/master/CITATION.txt>`_
+- `xarray <https://github.com/pydata/xarray/blob/main/CITATION.cff>`_
 
 
 ICESat-2 Data
 -------------
-ICESat-2 data citation depends on the exact dataset used. Citation information for each data product can be found through the `NSIDC website <https://nsidc.org/data/icesat-2/data-sets>`_.
+ICESat-2 data citation depends on the exact dataset used.
+Citation information for each data product can be found through the `NSIDC website <https://nsidc.org/data/icesat-2/data-sets>`_.

CONTRIBUTORS.rst

@@ -2,7 +2,7 @@ Project Contributors
 ====================
 
 The following people have made contributions to the project (in alphabetical
-order by last name) and are considered "The icepyx Developers".
+order) and are considered "The icepyx Developers".
 Thanks goes to these wonderful people (`emoji key <https://allcontributors.org/docs/en/emoji-key>`_):
 
 .. raw:: html