How to cite JupyterLab #144
Labels
enhancement
New feature or request
Comments
|
Copying the people who spoke during the team meeting @afshin @ellisonbg @bollwyvl @williamstein |
|
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. |
|
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? |
On the technical side of author handling in Zenodo:
We can include non-code contributors manually, or for automated releases we can include them using the
There is a very minor technical issue with this approach: zenodo/zenodo#1956 but according to zenodo/zenodo#1737 (comment) it might be actually required because there might be still a limit on the number of authors (which could have changed since). |
|
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
<zenodo/zenodo#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 <zenodo/zenodo#1956> but
according to zenodo/zenodo#1737 (comment)
<zenodo/zenodo#1737 (comment)> 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
<#144 (comment)>,
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
|
|
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
> <zenodo/zenodo#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 <zenodo/zenodo#1956> but
> according to zenodo/zenodo#1737 (comment)
> <zenodo/zenodo#1737 (comment)> 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
> <#144 (comment)>,
> 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
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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:
The text was updated successfully, but these errors were encountered: