Citable Code #81

Merged
n merged 4 commits from ivan-paleo/Documentation:citable-code into master 2 years ago

Added some details on how to make your code (repo) citable.
As usual, open to comments and feedback!

Added some details on how to make your code (repo) citable. As usual, open to comments and feedback!
lhinderberger requested changes 2 years ago
lhinderberger left a comment

What an interesting topic - thank you for introducing it and writing this great article on the topic :)

As usual, you'll find a few remarks below:

What an interesting topic - thank you for introducing it and writing this great article on the topic :) As usual, you'll find a few remarks below:
key: CitableCode
title: Citable Code
parent: Collaborating
order: 3

For articles in sections that are not a step-by-step guide, let's not use order.

That makes it easier to find articles in the menu once alphabetical sorting is implemented -> #85.

For articles in sections that are not a step-by-step guide, let's not use `order`. That makes it easier to find articles in the menu once alphabetical sorting is implemented -> #85.
ivan-paleo marked this conversation as resolved
order: 3
---
The easiest way to share your code is obviously to send/post the URL of your repository. But this is not really viable in the long run becaue URLs can change.

Wording suggestions:

  • Share -> refer to your code
  • Let’s drop “Obviously” (this article describes what’s wrong with “obviously”: https://css-tricks.com/words-avoid-educational-writing/) :)
  • Second sentence: "But if you need to reliably refer to a specific version of your code in the long run, for example for scientific writing, this is not really viable, because URLs can change."
Wording suggestions: - Share -> refer to your code - Let’s drop “Obviously” (this article describes what’s wrong with “obviously”: https://css-tricks.com/words-avoid-educational-writing/) :) - Second sentence: "But if you need to reliably refer to a specific version of your code in the long run, for example for scientific writing, this is not really viable, because URLs can change."
ivan-paleo marked this conversation as resolved
![release](/assets/images/collaborating/citable-code/release.PNG)
In the new page, enter a version, select the branch, add a title and a description:

Suggested wording "choose a version number for your new release" because "enter a version" suggests the version already exists.

Maybe also "select the branch that contains the code that you want to release"

It's even more complicated - its either choosing an existing Git tag or creating a new one from the latest commit.

Right away, I don't know of a more elegant way of writing it though.

~~Suggested wording "choose a version number for your new release" because "enter a version" suggests the version already exists.~~ ~~Maybe also "select the branch that contains the code that you want to release"~~ It's even more complicated - its either choosing an existing Git tag or creating a new one from the latest commit. Right away, I don't know of a more elegant way of writing it though.
Poster

I think that your suggestion is still better than what I wrote. In any case, it constitutes a good starting point for future improvements.
Maybe we should consider adding details about releases in a separate documentation article (we would then link to it in this article about citable code).

I think that your suggestion is still better than what I wrote. In any case, it constitutes a good starting point for future improvements. Maybe we should consider adding details about releases in a separate documentation article (we would then link to it in this article about citable code).

That's a good idea -> I created issue nr. #88 for that

That's a good idea -> I created issue nr. #88 for that
ivan-paleo marked this conversation as resolved
![new-release](/assets/images/collaborating/citable-code/new-release.PNG)
You can either save as a draft, or publish the release already.

already -> outright

already -> outright
ivan-paleo marked this conversation as resolved
## Download the ZIP archive
If you did create a release, download the ZIP archive of the source code on the `Releases` tab of your repository, as shown in the previous screenshot.
If not, you can simply download the ZIP archive of the repository (see section Clone in [Clone & Commit via Web](/content/git/clone-commit-via-web)).

Please remove the /content prefix from your link.

Please remove the `/content` prefix from your link.
ivan-paleo marked this conversation as resolved
## Upload the ZIP archive to an online repository
There are many online repositories made specifically for research, e.g. [Zenodo](https://zenodo.org/), [Figshare](https://figshare.com/), [Dryad](https://datadryad.org/), [OSF](https://osf.io/)... Others might be more appropriate for other uses.
Upload the ZIP archive to one of them and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that every one accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.

Typo: every one -> everyone

Typo: every one -> everyone
ivan-paleo marked this conversation as resolved
Upload the ZIP archive to one of them and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that every one accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.
> WIP: An interface between Zenodo and Codeberg is currently being considered. This would make the process smoother.

Hehe, I threw the idea around, yes - but that's nothing "official" 😉

We should rephrase that to: "It should be possible to write an integration between Codeberg and one of the DOI repositories to make citing code a lot smoother. If you're interested, you may want to have a look at Codeberg/Community#295"

Hehe, I threw the idea around, yes - but that's nothing "official" :wink: We should rephrase that to: "It should be possible to write an integration between Codeberg and one of the DOI repositories to make citing code a lot smoother. If you're interested, you may want to have a look at [Codeberg/Community#295](https://codeberg.org/Codeberg/Community/issues/295)"
ivan-paleo marked this conversation as resolved
> WIP: An interface between Zenodo and Codeberg is currently being considered. This would make the process smoother.
## Share the DOI
Finally, get the DOI from the online repository. This is the permanent URL you can share and use for citation without any risk.

Let's drop "without any risk" and replace it with "in scientific writing".

That is, because statements like "without any risk" might be interpreted as an implied warranty (which we do not provide).

Let's drop "without any risk" and replace it with "in scientific writing". That is, because statements like "without any risk" might be interpreted as an implied warranty (which we do not provide).
ivan-paleo marked this conversation as resolved
lhinderberger added the
Status: Ready for Review
Kind: Documentation
labels 2 years ago
lhinderberger changed title from WIP: Citable Code to Citable Code 2 years ago
lhinderberger added
Status: Review
and removed
Status: Ready for Review
labels 2 years ago
Poster

I have made the changes based on your comments.
I have also added the webP images!

I have made the changes based on your comments. I have also added the webP images!
lhinderberger requested changes 2 years ago
lhinderberger left a comment

Very nice! :) The only thing that needs to be changed as far as I'm concerned is the filename of new-release.PNG -> new-release.png, as in #78. Let's focus the discussion on the solution for the Windows-related filename casing issue in that PR.

Very nice! :) The only thing that needs to be changed as far as I'm concerned is the filename of `new-release.PNG` -> `new-release.png`, as in #78. Let's focus the discussion on the solution for the Windows-related filename casing issue in that PR.
Poster

It should be fixed now. I'll pay attention to that issue next time!

It should be fixed now. I'll pay attention to that issue next time!
lhinderberger approved these changes 2 years ago
lhinderberger left a comment

Thanks! :) 👍

This now needs a second reviewer and can then be merged to master.

Thanks! :) 👍 This now needs a second reviewer and can then be merged to master.
n requested changes 2 years ago
n left a comment
Collaborator

Looks good except for a small change.

Looks good except for a small change.
n reviewed 2 years ago
Upload the ZIP archive to one of them and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that everyone accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.
> It should be possible to write an integration between Codeberg and one of the DOI repositories to make citing code a lot smoother. If you’re interested, you may want to have a look at Codeberg/Community#295
n commented 2 years ago
Collaborator

We should add a hyperlink to the issue here.

We should add a hyperlink to the issue here.
ivan-paleo marked this conversation as resolved
Poster

Thanks for the review! The hyperlink should be fixed now.

Thanks for the review! The hyperlink should be fixed now.
n merged commit d2bc1a8c6d into master 2 years ago
n approved these changes 2 years ago
n left a comment
Collaborator

Thanks!

Thanks!

Reviewers

lhinderberger approved these changes 2 years ago
n approved these changes 2 years ago
The pull request has been merged as d2bc1a8c6d.
Sign in to join this conversation.
No reviewers
No Milestone
No Assignees
3 Participants
Notifications
Due Date

No due date set.

Dependencies

This pull request currently doesn't have any dependencies.

Loading…
There is no content yet.