Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Update citation file with JOSS paper reference #496

Merged
merged 21 commits into from
Nov 2, 2021
+26 −9
Merged

DOC: Update citation file with JOSS paper reference #496

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
816c44e
Update citation file with JOSS paper reference
Lucia-Fonseca Sep 10, 2021
cb781e0
Create file to link the citation rst file to docs
Lucia-Fonseca Sep 10, 2021
a2e7eab
Add link to the citation file in the docs
Lucia-Fonseca Sep 10, 2021
f2fa12b
Add titel to the citation guidelines
Lucia-Fonseca Sep 10, 2021
d4078de
Create BibTeX download button'
Lucia-Fonseca Sep 10, 2021
0f52a9c
Fix external link
Lucia-Fonseca Sep 10, 2021
5554702
Move citation from developer to project doc folder
Lucia-Fonseca Sep 10, 2021
8106e3e
Add citatio to the project toctree in index
Lucia-Fonseca Sep 10, 2021
a66e6c3
Fix link to citation file
Lucia-Fonseca Sep 10, 2021
6019b13
Add blank line
Lucia-Fonseca Sep 10, 2021
bdb2de0
Fix link to bib file
Lucia-Fonseca Sep 10, 2021
be1673d
Delete BibTeX file
Lucia-Fonseca Sep 13, 2021
c3dc091
Update text
Lucia-Fonseca Sep 13, 2021
b92ae35
Fix badges
Lucia-Fonseca Sep 13, 2021
d2e4504
Eliminate unnecessary options for badges
Lucia-Fonseca Sep 13, 2021
68dfd64
Add admonition
Lucia-Fonseca Sep 13, 2021
4078b4e
Edit text around the important note
Lucia-Fonseca Sep 13, 2021
82a0ba1
Edit text
Lucia-Fonseca Sep 13, 2021
e08e56f
Change admonition to pull-quite
Lucia-Fonseca Sep 13, 2021
1d7b1ad
Update CITATION.rst
rrjbca Nov 2, 2021
9c7e7f8
Merge branch 'main' into citation
rrjbca Nov 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions CITATION.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,27 @@
Citation Guidelines
===================

|JOSS| |Zenodo|


If you use SkyPy for work or research presented in a publication (whether
directly, or as a dependency to another package) we recommend and encourage
directly, or as a dependency of another package) we recommend and encourage
the following acknowledgment:

This research made use of SkyPy, a Python package for forward modeling
astronomical surveys (SkyPy Collaboration, 2020).
astronomical surveys (Amara et. al., 2021, SkyPy Collaboration, 202x).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apologies if I have missed discussions which already address these points.

  • Are we happy with 'Amara et al' or would another 'SkyPy Collaboration' be the preferred style? I appreciate there are probably reasons for this I have missed!
  • We could do the work for the user of including the most up to date version year/reference, which I guess would just require changing as part of each new release.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Are we happy with 'Amara et al' or would another 'SkyPy Collaboration' be the preferred style? I appreciate there are probably reasons for this I have missed!

"SkyPy Collaboration" isn't listed as an author on the JOSS paper, their template wouldn't allow it. Are you suggesting that people cite it as SkyPy Collaboration 2021 regardless? Would that work with ADS etc?

  • We could do the work for the user of including the most up to date version year/reference, which I guess would just require changing as part of each new release.

But then if somebody is using an older version they shouldn't be citing the most up to date version. It might be possible that for each release the published documentation give the corresponding DOI, but only if we can reserve zenodo DOIs before me make the release. As our Zenodo admin could you investigate this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not happy with Amara et al. either, if we could do SkyPy Collaboration and not mess up with ADS I would go for it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I cannot find anything in the ADS FAQ to answer this...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it is possible to reserve a zenodo DOI when using the github webhook, so we would have to revert to manual submissions.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this something we want to try?
I'd rather have SkyPy Collaboration rather than Amara et al. 2021 but:

  • Is it worth delaying the release?
  • Sutieng's paper is ready and they cite Amara et al 2021.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my opinion, releasing this PR is our single highest priority. The proposed guidelines are adequate and these side issues are unresolved and unnecessarily holding us up. Like it or not, Amara et al 2021 is the correct citation given by both ADS and JOSS. I agree that our citation guidelines should be consistent with ADS in the first instance. I'm also against modifying the ADS entry at the expense of consistency with the entry on the JOSS website. Similarly, reserving a DOI has not been tested with the GitHub webhook and putting the wrong DOI in our citation guidelines could be incredibly harmful. I would suggest trying to reserve a DOI for our next release and if we can demonstrate that it works then integrate reserved DOIs into the citation guidelines for future releases.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't disagree necessarily with any of this, but I think it is not fair labeling this a "side issue" or "unnecessary". We agreed pretty early on that all publications would be authored by "SkyPy collaboration" with an alphabetical author list following. Now reneging on this merits at least a discussion, and probably a much more visible one than hidden in this PR somewhere.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Totally agree these are decisions beyond the scope of this PR and review that should be discussed by the collaboration. But the current proposal is at least accurate and waiting for the resolution of that discussion could cost us citations. The guidelines can always be updated in the future.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, we'd need a conversation with the collaboration and we can also merge this as it is for the sake of the v0.5 release. After all, the issue is not about the author list (which I agree it's not a secondary issue but it is not a GitHub issue either)


where the citations are to our publication in the `Journal of Open Source
Software`_ and the `Zenodo DOI`_ for the specific version of the software that
you used. We also encourage citations within the main text wherever
appropriate. DOIs and BibTeX keys are available through the links above.

.. _Journal of Open Source Software: https://joss.theoj.org/papers/10.21105/joss.03056
.. _Zenodo DOI: https://zenodo.org/record/3755531


where (SkyPy Collaboration, 2020) is a citation to the software DOI for the
specific version that you used. We also encourage you to cite the software DOI
in the main text wherever appropriate. DOIs and BibTeX keys for each release
can be found on Zenodo_.
.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.03056/status.svg
:target: https://doi.org/10.21105/joss.03056

.. _Zenodo: https://zenodo.org/record/3755531
.. |Zenodo| image:: https://zenodo.org/badge/doi/10.5281/zenodo.4475347.svg
:target: https://doi.org/10.5281/zenodo.3755531
6 changes: 4 additions & 2 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@ intention the simulations can then be compared to data as part of an inference
pipeline.

.. Important:: If you use SkyPy for work presented in a publication or talk
please help the project via proper `citation or acknowledgement
<https://github.com/skypyproject/skypy/blob/main/CITATION.rst>`_.
please follow our :doc:`project/citation`.



.. _getting-started:

Expand Down Expand Up @@ -74,6 +75,7 @@ Project details
:maxdepth: 1

project/code_of_conduct
project/citation


*****
Expand Down
1 change: 1 addition & 0 deletions docs/project/citation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. include:: ../../CITATION.rst