124

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?

  • 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
  • @charlespwd Welcome to Academia.SE! :) I edited the question a bit to make it working well with StackExchange way of asking question (so you can get the best answers). I hope that you don't mind. If you do, just revert my changes. – Piotr Migdal Nov 11 '13 at 16:18
  • 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
  • 1
    See also this discussion: lists.software-carpentry.org/pipermail/… – Piotr Migdal Nov 11 '13 at 22:13
  • 2
    Take a look at this: [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
60

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.

  • 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 3:23
  • 12
    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". – dgraziotin Dec 2 '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 3 '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 4 '13 at 17:05
  • 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
65

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.

  • 2
    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
  • Any particular reason for the anonymous downvote? – Piotr Migdal Nov 11 '13 at 20:53
  • 1
    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
  • No. I would search his real name for that username elsewhere. – Erkin Alp Güney Feb 8 '18 at 8:50
15

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

12

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.

  • 20
    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 1 '14 at 0:51
6

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/

0

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.

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.