search

jupyterlab / frontends-team-compass

A repository for team interaction, syncing, and handling meeting notes across the JupyterLab ecosystem.
https://jupyterlab-team-compass.readthedocs.io/en/latest/
BSD 3-Clause "New" or "Revised" License
59 stars 30 forks source link

How to cite JupyterLab #144

Open isabela-pf opened 2 years ago

isabela-pf commented 2 years ago

Problem

When someone wants to cite JupyterLab specifically, we have no guidance for how they should do so. Other projects in Jupyter and in the wider ecosystem do this, so we receive recurring issues across GitHub and Discourse asking for our recommendation.

Proposed Solution

I propose we agree on a standard way that we recommend citing JupyterLab. This solution could live on the readme and JupyterLab documentation.

What I do not know is how we want to recommend citing. This part is still very open for discussion! Some ideas have been listed under Additional context below.

Additional context

I'm opening this issue now in response to the question in jupyterlab/jupyterlab #12176 and the related discussion at our March 16 JupyterLab team meeting notes.

From the March 16 meeting, the following ideas were shared:

Other notes:

isabela-pf commented 2 years ago

Copying the people who spoke during the team meeting @afshin @ellisonbg @bollwyvl @williamstein

krassowski commented 2 years ago

A quick way for getting a DOI with just a press of a button would to use https://zenodo.org/ (a CERN-maintained service for software and data sharing) which integrates seamlessly with GitHub. Each release automatically gets a DOI and there is also a catch-all DOI which stays the same between releases. For an example see python-pillow/Pillow. It would not preclude a JOSS submission in the future.

jasongrout commented 2 years ago

I like the idea of the zenodo proposal. One possible concern with having a DOI for every version is that citations get diluted across many different versions, versus having a single DOI for the overall JupyterLab project and just stating which version is being referred to.

One other question that came up in the dev meeting: should there be an automated list of authors (is it code committers, ignoring non-code contributions?), or do we just do a blanket "Project Jupyter Contributors" like we do for the license?

krassowski commented 2 years ago

an automated list of authors (is it code committers, ignoring non-code contributions?)

On the technical side of author handling in Zenodo:

  1. Contributors are added to the list of authors automatically based on the list of users who had committed to the code up to the point of the release
  2. Authors can be added/removed manually (/affiliation/ORCID modified) via the web UI
  3. There is a special .zenodo.json file (recommended in geodynamics' Zenodo Best Practices) which is well documented in the Zenodo API; this allows to automatically fill in (/or overwrite) the metadata of each release with:
    • affiliations and ORCID for authors
    • keywords
    • references to related published papers
    • grants numbers (which would be a nice gesture towards funders like CZI)
    • of note there are separate fields for creators (empty by default?) and contributors
  4. Some repositories use an AUTHORS.md file (see the description in pygmt and examples: Trixi.jl, pygmt). It seems that Zenodo does not support this and instead some organizations: a) have custom Zenodo release pipelines (see EIC/acts) which parse this AUTHORS.md file over the default zenodo web hooks or b) make Zenodo releases manually (like pygmt). This provides a full control of the metadata.

We can include non-code contributors manually, or for automated releases we can include them using the .zenodo.json file however it seems that we can only add people using creators field - until https://github.com/zenodo/zenodo/issues/1737 is resolved we can only overwrite contributors (rather than extend it).

or do we just do a blanket "Project Jupyter Contributors" like we do for the license?

There is a very minor technical issue with this approach: https://github.com/zenodo/zenodo/issues/1956 but according to https://github.com/zenodo/zenodo/issues/1737#issuecomment-704861970 it might be actually required because there might be still a limit on the number of authors (which could have changed since).

ellisonbg commented 2 years ago

I don't have strong feelings about Zenodo versus JOSS or starting with Zenodo and later submitting a JOSS article, however I think it is critical that we follow the author list guidelines and process that Jupyter has set out in this doc:

https://github.com/jupyter/governance/blob/master/papers.md

We spent a good amount of time on that to ensure that people are able to get credit for work they have done. As long as Zenodo can handle those requirements that seems like a fine start.

I do think Jason Grout had a good point about having a DOI/version dilutes the citations and makes it difficult to track the real impact of the project. At the same time, new contributors join over time, and I would like to be able to add them to the author list, so maybe a DOI per major version gives us more flexibility in adding new authors over time.

On Wed, Apr 6, 2022 at 10:55 AM Michał Krassowski @.***> wrote:

an automated list of authors (is it code committers, ignoring non-code contributions?)

On the technical side of author handling in Zenodo:

  1. Contributors are added to the list of authors automatically based on the list of users who had committed to the code up to the point of the release
  2. Authors can be added/removed manually (/affiliation/ORCID modified) via the web UI
  3. There is a special .zenodo.json file (recommended in geodynamics' Zenodo Best Practices https://github.com/geodynamics/best_practices/blob/master/ZenodoBestPractices.md) which is well documented in the Zenodo API https://developers.zenodo.org/#add-metadata-to-your-github-repository-release; this allows to automatically fill in (/or overwrite) the metadata of each release with:
    • affiliations and ORCID for authors
    • keywords
    • references to related published papers
    • grants numbers (which would be a nice gesture towards funders like CZI)
    • of note there are separate fields for creators (empty by default?) and contributors
  4. Some repositories use an AUTHORS.md file (see the description in pygmt https://github.com/GenericMappingTools/pygmt/blob/main/AUTHORSHIP.md#authorship-on-zenodo-archives-of-releases and examples: Trixi.jl https://github.com/trixi-framework/Trixi.jl/blob/v0.4.28/AUTHORS.md, pygmt https://github.com/GenericMappingTools/pygmt/blob/main/AUTHORS.md). It seems that Zenodo does not support this and instead some organizations: a) have custom Zenodo release pipelines (see EIC/acts https://github.com/ECCE-EIC/acts/blob/e95c98ff548f5bf04709ec343aa2d1f3e8869164/CI/make_release.py#L425-L457) which parse this AUTHORS.md file over the default zenodo web hooks or b) make Zenodo releases manually (like pygmt). This provides a full control of the metadata.

We can include non-code contributors manually, or for automated releases we can include them using the .zenodo.json file however it seems that we can only add people using creators field - until zenodo/zenodo#1737 https://github.com/zenodo/zenodo/issues/1737 is resolved we can only overwrite contributors (rather than extend it).

or do we just do a blanket "Project Jupyter Contributors" like we do for the license?

There is a very minor technical issue with this approach: zenodo/zenodo#1956 https://github.com/zenodo/zenodo/issues/1956 but according to zenodo/zenodo#1737 (comment) https://github.com/zenodo/zenodo/issues/1737#issuecomment-704861970 it might be actually required because there might be still a limit on the number of authors (which could have changed since).

— Reply to this email directly, view it on GitHub https://github.com/jupyterlab/team-compass/issues/144#issuecomment-1090565290, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAGXUC2BY475H37RT4UFE3VDXF2HANCNFSM5SJ4UP3Q . You are receiving this because you were mentioned.Message ID: @.***>

-- Brian E. Granger

Senior Principal Technologist, AWS AI/ML @.***) On Leave - Professor of Physics and Data Science, Cal Poly @ellisonbg on GitHub

ellisonbg commented 2 years ago

Looking at the Jupyter paper guidelines ( https://github.com/jupyter/governance/blob/master/papers.md) a bit more to refresh my memory. Looks like the processing part about what it teams to be an author and the processing for notifying authors is focused on JOSS articles. Our original intent was to use JOSS for these types of papers that are meant to be the "official citation" for a subproject. If we want to use Zenodo for that I believe the intended spirit of the doc would for us to use that process and criteria for assembling the author list for the zenodo citation. For those who haven't read the doc, it includes a concrete set of authorship criteria (who can be an author?), a process for identifying those authors, and a coordinator role that helps it all get done (both the writing and authorship stuff).

On Thu, Apr 7, 2022 at 11:31 AM Brian Granger @.***> wrote:

I don't have strong feelings about Zenodo versus JOSS or starting with Zenodo and later submitting a JOSS article, however I think it is critical that we follow the author list guidelines and process that Jupyter has set out in this doc:

https://github.com/jupyter/governance/blob/master/papers.md

We spent a good amount of time on that to ensure that people are able to get credit for work they have done. As long as Zenodo can handle those requirements that seems like a fine start.

I do think Jason Grout had a good point about having a DOI/version dilutes the citations and makes it difficult to track the real impact of the project. At the same time, new contributors join over time, and I would like to be able to add them to the author list, so maybe a DOI per major version gives us more flexibility in adding new authors over time.

On Wed, Apr 6, 2022 at 10:55 AM Michał Krassowski < @.***> wrote:

an automated list of authors (is it code committers, ignoring non-code contributions?)

On the technical side of author handling in Zenodo:

  1. Contributors are added to the list of authors automatically based on the list of users who had committed to the code up to the point of the release
  2. Authors can be added/removed manually (/affiliation/ORCID modified) via the web UI
  3. There is a special .zenodo.json file (recommended in geodynamics' Zenodo Best Practices https://github.com/geodynamics/best_practices/blob/master/ZenodoBestPractices.md) which is well documented in the Zenodo API https://developers.zenodo.org/#add-metadata-to-your-github-repository-release; this allows to automatically fill in (/or overwrite) the metadata of each release with:
    • affiliations and ORCID for authors
    • keywords
    • references to related published papers
    • grants numbers (which would be a nice gesture towards funders like CZI)
    • of note there are separate fields for creators (empty by default?) and contributors
  4. Some repositories use an AUTHORS.md file (see the description in pygmt https://github.com/GenericMappingTools/pygmt/blob/main/AUTHORSHIP.md#authorship-on-zenodo-archives-of-releases and examples: Trixi.jl https://github.com/trixi-framework/Trixi.jl/blob/v0.4.28/AUTHORS.md, pygmt https://github.com/GenericMappingTools/pygmt/blob/main/AUTHORS.md). It seems that Zenodo does not support this and instead some organizations: a) have custom Zenodo release pipelines (see EIC/acts https://github.com/ECCE-EIC/acts/blob/e95c98ff548f5bf04709ec343aa2d1f3e8869164/CI/make_release.py#L425-L457) which parse this AUTHORS.md file over the default zenodo web hooks or b) make Zenodo releases manually (like pygmt). This provides a full control of the metadata.

We can include non-code contributors manually, or for automated releases we can include them using the .zenodo.json file however it seems that we can only add people using creators field - until zenodo/zenodo#1737 https://github.com/zenodo/zenodo/issues/1737 is resolved we can only overwrite contributors (rather than extend it).

or do we just do a blanket "Project Jupyter Contributors" like we do for the license?

There is a very minor technical issue with this approach: zenodo/zenodo#1956 https://github.com/zenodo/zenodo/issues/1956 but according to zenodo/zenodo#1737 (comment) https://github.com/zenodo/zenodo/issues/1737#issuecomment-704861970 it might be actually required because there might be still a limit on the number of authors (which could have changed since).

— Reply to this email directly, view it on GitHub https://github.com/jupyterlab/team-compass/issues/144#issuecomment-1090565290, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAGXUC2BY475H37RT4UFE3VDXF2HANCNFSM5SJ4UP3Q . You are receiving this because you were mentioned.Message ID: @.***>

-- Brian E. Granger

Senior Principal Technologist, AWS AI/ML @.***) On Leave - Professor of Physics and Data Science, Cal Poly @ellisonbg on GitHub

-- Brian E. Granger

Senior Principal Technologist, AWS AI/ML @.***) On Leave - Professor of Physics and Data Science, Cal Poly @ellisonbg on GitHub