252

I am working on a honours thesis and have developed a Fortran library that I would like to cite in it.

In some places they suggest to quote the documentation of the project but this is something I plan to do in the future and isn't done yet. The only documentation I have right now is the README file and the code itself.

What would be an acceptable way of directing a reader to my work on Github?

(bonus) Is there a BibTeX way to do it?

Piotr Migdal
  • 26,252
  • 10
  • 74
  • 126
charlespwd
  • 2,623
  • 2
  • 13
  • 5
  • 1
    I think energynumbers answer is correct in terms of what is "correct" in academic literature. However, if the immediate issue is "I need to let a reader of the thesis/dissertation that I'm working on right now see the software", then (low-tech as it seems) you could consider including the source code in an appendix. How practical this is may depend on its length... Or ask your supervisor whether they're happy for you to provide a github link and what the format should be. Also, welcome to Stackexchange :-) – Flyto Nov 11 '13 at 15:54
  • 1
    @SimonWaldman: 7K lines of code spread over multiple modules is definitively not something I can include in an appendix. My colleague did include his MATLAB code in his thesis but I found it to be a terrible way to share code as you cannot reuse it easily (copying it in matlab would ignore the tabbing, etc.). – charlespwd Nov 11 '13 at 16:25
  • @charlespwd ha, fair enough. And I agree that it's a terrible way to share code. But if this is for an examinable thesis rather than a published paper, I think the correct answer is "whatever your supervisor is happy with" ;-) – Flyto Nov 11 '13 at 17:01
  • 1
    See also this discussion: http://lists.software-carpentry.org/pipermail/discuss_lists.software-carpentry.org/2013-October/001048.html – Piotr Migdal Nov 11 '13 at 22:13
  • ^ There are so many great points I think they are worth compiling into an answer, much better than all current ones! – Piotr Migdal Nov 11 '13 at 22:18
  • 3
    Take a look at this: [https://github.com/blog/1840-improving-github-for-science]. This might answer at least a part of your question. – Dohn Joe May 15 '14 at 18:18

8 Answers8

141

I would go with:

P.W.D. Charles, Project Title, (2013), GitHub repository, https://github.com/charlespwd/project-title

Or a bit different, depending on your citation style. Just is is crucial to include: author, title (if style includes it), year and link.

Of course if you do have a publication related to this piece of code (even if only by fact it is your first publication basing on this code), don't forget to cite is as well! (In the current academic system it is all that counts.)

And respective BibTeX entry:

@misc{Charles2013,
  author = {Charles, P.W.D.},
  title = {Project Title},
  year = {2013},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/charlespwd/project-title}},
  commit = {4f57d6a0e4c030202a07a60bc1bb1ed1544bf679}
}

Beware, this above are improvisations (especially the BibTeX entry), not standards.

Even for more established and citable things there are not set standards, see e.g.:

See also:

EDIT:

See also how to assign DOI to a particular commit in your repository.

Community
  • 1
Piotr Migdal
  • 26,252
  • 10
  • 74
  • 126
  • 3
    Maybe we can agree on something like this for a standard. I don't see why traditional journals are better than GitHub repositories to publish papers. In this case I'd upload the LaTeX sources to the repository and provide a link to the PDF. I'm seriously thinking about doing this, there is even some review process, and reviewers can open issues in the repository :-m This would be free for authors and provide open access, promote collaboration, etc. – Trylks Nov 11 '13 at 18:50
  • 2
    If the repo owner doesn't make their full name known, would you suggest using their GitHub user name instead? – NewNameStat Aug 30 '16 at 16:32
  • 2
    No. I would search his real name for that username elsewhere. – Erkin Alp Güney Feb 08 '18 at 08:50
  • 2
    Some github users do not use their real name and make it very difficult to find it. – qwr May 04 '21 at 23:57
  • Why not use url={https://github.com/charlespwd/project-title} – qwr May 05 '21 at 00:02
  • What's the year in the case that I'm not referring to a specific commit but to the repo in general? – stefanbschneider Nov 10 '21 at 14:42
  • 1
    @Trylks - realize your comment is from 2013, but the Journal of Open Source Software (JOSS) does all of their review on github. See https://github.com/openjournals/joss-reviews/issues/4368 for instance. – jkr Jul 23 '22 at 23:57
78

I was asked to provide my comment as an answer, so here it is. It is yet another way to cite software. However, it requires some effort from the software authors.

I developed an Open Source Web tool for modeling and gathering data when following a certain theory/methodology in software engineering. Here is how you would cite it:

Graziotin, D and Abrahamsson, P 2013. A Web-based modeling tool for the SEMAT Essence theory of software engineering. Journal of Open Research Software 1(1):e4, DOI: http://dx.doi.org/10.5334/jors.ad

This is possible because I opted to publish a software paper in the Journal of Open Research Software. It is a fully Open Access journal. This journal only accepts software papers on open source software for research.

A software paper is a special kind of paper, which describes the software-e.g., what is it about, implementation and architecture, its availability, and its reuse potential. The editorial process works as in any other research venue, and articles are peer-reviewed.

The article processing charges are 25GBP. However, they can be fully waived if you cannot afford them.

What it is nice with this approach is that researchers have an extra motivation to open their software for research: they get a publication for that, plus citations. Additionally, writing a software paper is far easier than writing a methodology paper.

I wrote a review of the journal on my blog. TL;DR; Great experience, go for it.

TheTechRobo the Nerd
  • 103
  • 3
  • Nice review of the Journal of Open Research Software. I've never heard of this journal before, and I'm impressed by your description of its review process. I'm particularly impressed that they critiqued the code. If anyone else has submitted there, can you comment? – Faheem Mitha Nov 13 '13 at 03:23
  • 21
    Just to clarify, for future visitors of this question. I have just joined the Editorial board of the journal. However, this answer was written when there was no "competing interest". –  Dec 02 '13 at 14:03
  • 3
    @FaheemMitha I've reviewed for the JORS and agree completely with this answer. Yes, I reviewed the code as per the JORS reviewer guidelines. I've reviewed 'Software Papers' in traditional domain journals, and occasionally gotten editorial pushback for my reviewing the code as well as the paper: see carlboettiger.info/2013/06/13/what-I-look-for-in-software-papers.html – cboettig Dec 03 '13 at 20:44
  • @cboettig Thanks for the link. I read your blog article. It was good, though a little too R specific. Do you have any idea of the current turnaround time between submission and a decision for JORS? Personally, I think a good thing to do is create a Debian package for your software. If done properly, it automatically addresses a bunch of issues. – Faheem Mitha Dec 04 '13 at 17:05
  • @FaheemMitha Yes, I was mostly referring to the comment string on that post, which reflects varied opinions of reviewing the software, rather than the contents of my post; sorry. Yes, Debian packages assure at least basic metadata are provided, but clearly are not ideal for a Windows audience, for example. Other package systems provide other +'s and -'s. JORS makes the authors speak to each of these issues. – cboettig Dec 04 '13 at 17:47
  • @cboettig Well, clearly one would only make a Debian package for fairly Unixy software. Most scientific software would work only on one of Windows and Linux anyway. – Faheem Mitha Dec 04 '13 at 21:02
  • 1
    Thank you so much for this. I have been looking for some time for an alternative to Computer Physics Communications which is Cost-Of-Knowledge compatible. This seems to fit the bill very nicely. – E.P. Jul 28 '14 at 16:12
  • I'd ralso ecommend the Journal of Open Source Software, it's a NUMFocus project, completely free AFAIK, and is designed to be developer friendly: https://joss.theoj.org/ – Bar Jan 18 '18 at 10:41
78

GitHub has now added built-in citation support (https://twitter.com/natfriedman/status/1420122675813441540). Simply add a CITATION.cff file ( https://citation-file-format.github.io/) to your repo and a citation widget will be added to the sidebar:

A "Cite this repository" widget on the sidebar, under the "Readme". The widget says "Cite this repository: If you use this software in your work, please cite it using the following metadata." and a "Learn more" link. There are APA and BibTeX citation options, a copy button, and a link back to "View citation file".

Mithical
  • 109
  • 1
  • 5
Smajjk
  • 904
  • 6
  • 3
26

Now they become somehow citable by providing DOI references. That was on their 14th of May news: https://github.com/blog/1840-improving-github-for-science

Shahryar
  • 535
  • 4
  • 4
19

GitHub now offers citation as a service, at least with Zenodo. This guide instructs how to connect your accounts and get a DOI with your work:
https://guides.github.com/activities/citable-code/

albert
  • 317
  • 2
  • 8
15

The underlying question seems to be how to get citable software.

There is a traditional method for doing this.

You write a methodology paper describing the software, how it was built, what it does. You can provide the source code as supplementary information.

And then you cite that paper, in future papers where you apply the software.

410 gone
  • 25,792
  • 6
  • 79
  • 135
  • 32
    I think that as a scientific society, it is crucial to develop a way of citing other things than journal publication (e.g. code, data). Otherwise science will never move into the 21st century. – Piotr Migdal Nov 11 '13 at 16:12
  • 3
    @PiotrMigdal I agree and I hope there will be better ways to cite non-journal knowledge. However this is what there is now. – Trylks Nov 11 '13 at 16:38
  • 1
    @Trylks I know. So mine is a comment, not a downvote or anything. Anyway, the question is what to do when there is no accompanying journal entry (BTW: as of now I have the same problem). – Piotr Migdal Nov 11 '13 at 16:46
  • 1
    I hope though that you don't imply that we get rid of peer review in the 21st century? The good thing with this answer is that if a linked code repository and data are connected with a paper, then it was part of the review process. While when I'm citing just somebody's stuff somewhere on the web, it could be anything really.Not saying peer review is perfect,but that we really need to integrate it with the more modern interconnected work styles. – K.-Michael Aye Apr 01 '14 at 00:51
2

What I've seen most often is a footnote with the URL you want to provide, in this case the URL of your GitHub repository. This will point people even better because it will be in the same page, and sure it will not count for bibliographic statistics and your h-index, but it wasn't going to count anyway, at least not yet.

Trylks
  • 4,256
  • 4
  • 20
  • 30
0

Figshare provides a way to import a GitHub release and assigns a doi to it. I haven't tried this yet but it seems to be a good middle path between a software paper and citing just the repository.

Eekhoorn
  • 2,174
  • 1
  • 14
  • 23