openjournals / joss

The Journal of Open Source Software

The Journal of Open Source Software

The Journal of Open Source Software (JOSS) is a developer friendly journal for research software packages.

What exactly do you mean by 'journal'

The Journal of Open Source Software (JOSS) is an academic journal with a formal peer review process that is designed to improve the quality of the software submitted. Upon acceptance into JOSS, a CrossRef DOI is minted and we list your paper on the JOSS website.

Don't we have enough journals already?

In a perfect world, papers about software wouldn't be necessary. Unfortunately, for most researchers, academic currency relies on papers rather than software and citations are, thus, crucial for a successful career.

We built this journal because we believe that after you've done the hard work of writing great software, it shouldn't take weeks and months to write a paper¹ about your work.

You said developer friendly, what do you mean?

We have a simple submission workflow and extensive documentation to help you prepare your submission. If your software is already well documented then paper preparation should take no more than an hour.

¹ After all, this is just advertising.

The site

The JOSS submission tool is hosted at https://joss.theoj.org

JOSS Reviews

If you're looking for the JOSS reviews repository head over here: https://github.com/openjournals/joss-reviews/issues

Code of Conduct

In order to have a more open and welcoming community, JOSS adheres to a code of conduct adapted from the Contributor Covenant code of conduct.

Please adhere to this code of conduct in any interactions you have in the JOSS community. It is strictly enforced on all official JOSS repositories, the JOSS website, and resources. If you encounter someone violating these terms, please let the Editor-in-Chief (@arfon) or someone on the editorial board know and we will address it as soon as possible.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

⚙️ Development

PostgreSQL and Elasticsearch should be installed and running locally for JOSS to work

1. Create the database with bin/rails db:create
2. Run bin/rails s

joss's Issues

make URLs in submissions open in new windows

It would be nice if the URLs in a submission issue opened in a new window, rather than the same window.

For example, in https://github.com/openjournals/joss-reviews/issues/9, if I click on the "repository URL" in the first checkbox item, the submission content is replaced with the repository content in the same window.

Adding analytics services

• Google Analytics
• Honeybadger (or equivalent) for production errors

Need to email authors when they submit

We probably need to do this. They already get cc-ed on the review issue so perhaps we don't need to do this?

I'd like to review for JOSS

Need to credit rOpenSci review process

...as inspiration for what we're doing here.

/ cc @danielskatz

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Repository: https://github.com/arfon/fidgit

Build out command line tool to generate software metadata

Some initial work here for parsing the GitHub API: https://github.com/arfon/metamatter

Should we also ask authors to explicitly state the version of the software?

Currently people submit an archive of their software but we don't capture what version (i.e. v1.9.0 or SHA) of the software people are submitting. Should we?

Need to draft guidelines for authorship

Things to discuss/support:

• Who should be listed as an author (do all committers to a repository count?)
• How to handle authorship between releases of a software package?
  • Suggest publish major versions only (point authors to semantic versioning)
  • Suggest that authors between major versions should be only those authors that have contributed to to the delta
• What happens after acceptance?

abstract builder

Perhaps a form could be used to 'help' a submitter write an abstract, like "This software, [()], is intended to allow to . It does this by . It is written in <language(s)>. [It is based on .] [It relies on .] ..."

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474 - Assigned reviewer: @arfon

                          - Repository: https://github.com/arfon/fidgit
  

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Repository: https://github.com/arfon/fidgit

What does acceptance look like?

Once the review is complete acceptance is ideally:

• Generate CrossRef metadata based on paper.md & register DOI
• @whedon generates PDF based upon paper.md
• @whedon generates code.jsonld
• @whedon opens a PR to the author's repo with the code.jsonld, JOSS badge for the README and CrossRef DOI
• Update JOSS site with the entry #32

What does a JOSS badge look like?

Related to #43

Build editorial tool for handling submissions

Needs to:

• Check submission is in compliance with editorial policies
• Generate metadata for CrossRef
• ...

Decide what metadata we require for submission

This should probably be based on https://github.com/codemeta/codemeta and should include sufficient information to automagically complete the form on the journal submission page.

asdas

asdas

Need to decide what to show on paper 'show' page once accepted.

Related to #32

Add Dublin core meta tags for Google Scholar

Google Scholar has some pretty strict requirements for what is required for them to index us. We should make sure we're doing the right thing...

https://scholar.google.com/intl/us/scholar/inclusion.html

A responsive reading/browsing experience

JOSS currently doesn't render very nicely on a mobile device - lets fix that.

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Repository: https://github.com/arfon/fidgit

Need to move review issues to dedicated repo

Currently reviews are being posted here which doesn't seem quite right. We should probably set up a repo called joss-reviews or something similar where the actual submitted papers are reviewed.

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Repository: https://github.com/arfon/fidgit

I'd like to (try to) review for JOSS

Mostly around neuroscience.

Great idea for a journal !

We should explain what the purpose of paper.json is

Ultimately I'd like us to be able to build the full publication (and CrossRef metadata) based on the paper.json entry. For now though, it's a somewhat experimental feature but we'd still like authors to include one if possible.

I'd like to review for JOSS

JOSS logo

Decide how to handle authors

When people submit a paper they don't submit the author list (this is in paper.json). Once the paper is accepted though we need to list the authors on the accepted submission.

We should decide how to handle this...

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Repository: https://github.com/arfon/fidgit

What should/shouldn't the paper include?

Recording a comment from a conversation earlier today with @arfon and @danielskatz: should there be a way to allow discussion of implementation details or underlying theory (e.g., equations)? Or should that be mandated in the software documentation?

Some suggestions/options:

• Leave implementation/theory details in documentation.
• Keep "main" section of paper empty, but allow appendices.
• Allow "methodology" or "implementation details" (e.g.) section in paper

Paper should include software repo address and archive

Currently the compiled PDF doesn't include the software address or archive URL. This needs to be fixed!

/ cc @jakevdp

Build a basic web app to handle submissions and listings of papers

It would be pretty awesome if this could be a static site...

Should we only allow citations to DOIs in the paper?

This would make generating the CrossRef metadata much easier...

Whaddya think @karthik?

Will the review process be open? Will reviews be "published" with DOI? Will we allow continuous commenting/review of projects/papers?

Perhaps I missed this and we are all clear on this already but I was wondering about how "open" we have our review process.

Will we have private and anonymous peer review without publishing peer review data (comments and replies)? Or, do we publish/maintain submission history and peer review comments? If so, do we collect all review stuff into a single document and assign a DOI to this? Alternatively we could keep it online and open but not assign DOI so it is "cheaper". If we choose open peer-review I think I might be in favour of just showing the stuff rather than assigning DOI's to this.
Also if we show the full review process will it remain anonymous or not?

Will we allow continuous commenting/review of accepted works? i.e. post-publication review. Alternatively once we are recognized as an open journal people interested in post publication reviewing could do so on other platforms like https://www.scienceopen.com/. I'm in favour of just doing it that way.

Kevin

Need to decide what content to show on paper 'show' view.

i.e. how is this content generated?

Make a badge for authors to include in READMEs

It would be nice if people could add a badge to their repositories linking to JOSS and to show that their software has been reviewed.

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Assigned reviewer: @arfon
• Repository: https://github.com/arfon/fidgit

Decide editorial policy

Need guidance for authors and reviewers on:

• Open source requirements
• Level of documentation/testing required
• Authorship criteria (could/should this be generate from git log?)
• Method by which review should take place (e.g. Pull Request, Issues)
• What kind of software will we accept (anything with a research application)
• Can anyone submit a paper (yes)

Can papers be associated with individual Pull Requests?

This was an idea brought up by @arokem here at UW. He mentioned the common issue of assigning credit to contributions within individual projects...

For example, say I commit a new feature/algorithm to the astropy project, or even do a major refactoring of part of the package. Can we offer a way to get a citeable DOI for that work?

[WIP] Decide what to call this thing

Candidates include:

• Journal of Open Source Software
• Journal of Open Research Software (clashes with http://openresearchsoftware.metajnl.com)
• Research Software Reviews
• Journal of Brief Software Reviews (cribbing from http://beta.briefideas.org)

I'd like to review for JOSS

Need to autogenerate CrossRef submission XML once we have accepted the paper

For now this can be a button on the admin UI using a template similar to this one: https://gist.github.com/arfon/34012477c946265c38f1

Ultimately it would be good to automatically submit this to CrossRef from the UI.

Create a joss org?

Does it make sense to serve JOSS from a new GitHub org?

Need to decide content license for the papers

Probably CC-BY or CC0.

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Assigned reviewer: @arfon
• Repository: https://github.com/arfon/fidgit

User profile page

We could do with a user profile page for people to enter their email address and GitHub username

Fix checklist

https://github.com/openjournals/joss/blob/master/app/views/shared/review_body.erb

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Repository: https://github.com/arfon/fidgit

asdas

asdas

Submission: Fidgit

• Submitting author: http://orcid.org/0000-0002-3957-2474
• Repository: https://github.com/arfon/fidgit