JOSS publication requirements

[ChristopherMarais]

JOSS Submission Checklist for GTMNERR Science Dashboard

This checklist outlines the necessary steps to prepare the repository for a successful submission to the Journal of Open Source Software (JOSS).

---

✅ Essential Files & Metadata

These items are required by JOSS for a submission to be considered.

• Add an OSI-approved LICENSE file.

  • Create a file named LICENSE or LICENSE.md in the root of the repository.
  • Choose a license (e.g., MIT, GPL-3, Apache 2.0). You can use choosealicense.com for help.

• Create the paper.md file.

  • This is a short (250-1000 word) paper describing the research application of the software.
  • It must be in the root of the repository.
  • Follow the JOSS Paper Format guidelines.
  • Include a title, summary, author list with affiliations, and statement of need.

• Create a references.bib file.

  • This file will contain all references cited in paper.md in BibTeX format.
  • Ensure the .bib file is referenced correctly within the paper.md file.

---

👍 Recommended Files for Community & Discoverability

These files are not strictly required but are best practices that JOSS reviewers look for.

• Add a CONTRIBUTING.md file.

  • Explain how others can contribute to the project (e.g., reporting bugs, submitting pull requests).

• Add a CODE_OF_CONDUCT.md file.

  • Adopt a code of conduct to foster a welcoming community. The Contributor Covenant is a good template.

• Generate a codemeta.json file.

  • This file provides standardized metadata about the software. JOSS provides an R script to help generate this.

---

🚀 Documentation & Local Usability

Reviewers must be able to easily install and run the software locally.

• Update the main README.md with clear instructions.

  • Add a dedicated section for local installation and execution. Include the following two methods:

  • Method 1: Running with R

    • List prerequisites (R version).
    • Provide a git clone command.
    • Provide a command to install all R package dependencies:

      install.packages(c(
        "shiny", "shinydashboard", "shinyjs", "shinyWidgets", "shinybusy",
        "bslib", "leaflet", "plotly", "sf", "dplyr", "readr", "lubridate",
        "stringr", "forcats", "tidyr", "ggplot2", "ggthemes", "scales",
        "viridis", "RColorBrewer", "cowplot"
      ))

    • Provide the command to launch the app: shiny::runApp()

  • Method 2: Running with Docker

    • List prerequisites (Docker Desktop).
    • Provide a git clone command.
    • Provide the command to build the Docker image: docker build -t gtm-dashboard -f 05_DASHBOARD/Dockerfile .
    • Provide the command to run the container: docker run -p 3838:3838 gtm-dashboard
    • Provide the URL to access the app: http://localhost:3838

• Add instructions for running tests.

  • Create a section in the README.md explaining how a user can run the tests located in the 04_Tests directory.

---

🔬 Final Review

Perform a final check against JOSS policies before submitting.

• Confirm software meets JOSS "substantial scholarly effort" criteria.

  • The software should represent a significant contribution (rule of thumb is >3 months of effort).
  • The code is feature-complete and well-structured.

• Confirm software meets criteria for web-based tools.

  • The application is built around a "core library" of functions and demonstrates rigorous design. Be prepared to explain this in the paper.md and review thread.

• Check for any potential conflicts of interest.

  • All authors must disclose any potential COIs at submission time.

• Review authorship list.

  • Ensure all major contributors are listed as authors and have agreed to be listed.

• Read through the full JOSS Submission Requirements one last time.