From f0931ca9e2eae826a7eee8731679115bf2cdfbfc Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 12 Mar 2024 16:00:32 -0700 Subject: [PATCH 1/2] splitting up guides --- docs/_static/css/joss.css | 7 + docs/conf.py | 12 +- docs/editing.md | 473 +++++------------------------ docs/editor_onboarding.md | 131 +++++++++ docs/editor_tips.md | 41 +++ docs/example_paper.md | 194 ++++++++++++ docs/expectations.md | 50 ++++ docs/index.rst | 15 +- docs/paper.md | 366 +++++++++++++++++++++++ docs/requirements.txt | 1 + docs/review_criteria.md | 2 +- docs/sample_messages.md | 96 ++++++ docs/submitting.md | 604 ++------------------------------------ 13 files changed, 1009 insertions(+), 983 deletions(-) create mode 100644 docs/_static/css/joss.css create mode 100644 docs/editor_onboarding.md create mode 100644 docs/editor_tips.md create mode 100644 docs/example_paper.md create mode 100644 docs/expectations.md create mode 100644 docs/paper.md create mode 100644 docs/sample_messages.md diff --git a/docs/_static/css/joss.css b/docs/_static/css/joss.css new file mode 100644 index 00000000..387a54d3 --- /dev/null +++ b/docs/_static/css/joss.css @@ -0,0 +1,7 @@ +.ul { + text-decoration: underline; +} + +.sc { + font-variant-caps: small-caps; +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index fc08ff33..77700da2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,8 +15,6 @@ # import os # import sys # sys.path.insert(0, os.path.abspath('.')) -import recommonmark -from recommonmark.transform import AutoStructify # -- Project information ----------------------------------------------------- @@ -66,7 +64,10 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] +html_static_path = ['_static'] +html_css_files = [ + 'css/joss.css' +] # -- Options for HTMLHelp output --------------------------------------------- @@ -127,3 +128,8 @@ # -- Extension configuration ------------------------------------------------- myst_heading_anchors=3 +myst_enable_extensions = [ + "attrs_inline", + "linkify", + "strikethrough" +] diff --git a/docs/editing.md b/docs/editing.md index 8073e219..c27361c7 100644 --- a/docs/editing.md +++ b/docs/editing.md @@ -8,6 +8,67 @@ JOSS editors manage the review workflow with the help of our bot, `@editorialbot To learn more about `@editorialbot`'s functionalities, take a look at our [dedicated guide](editorial_bot). ``` +## Overview of editorial process + +**Step 1: An author submits a paper.** + +The author can choose to select an preferred editor based on the information available in our biographies. This can be changed later. + +**Step 2: If you are selected as an editor you get @-mentioned in the pre-review issue.** + +This doesn’t mean that you’re the editor, just that you’ve been suggested by the author. + +**Step 3: Once you are the editor, find the link to the code repository in the `pre-review` issue** + +- If the paper is not in the default branch, add it to the issue with the command: `@editorialbot set branch-where-paper-is as branch`. + +**Step 4: The editor looks at the software submitted and checks to see if:** + +- There’s a general description of the software +- The software is within scope as research software +- It has an OSI-approved license + +**Step 5: The editor responds to the author saying that things look in line (or not) and will search for reviewer** + +**Step 6: The editor finds >= 2 reviewers** + +- Use the list of reviewers: type the command `@editorialbot list reviewers` or + look at use the [Reviewers Management System](https://reviewers.joss.theoj.org) +- If people are in the review list, the editor can @-mention them on the issue to see if they will review: e.g. `@person1 @person2 can you review this submission for JOSS?` +- Or solicit reviewers outside the list. Send an email to people describing what JOSS is and asking if they would be interested in reviewing. +- If you ask the author to suggest potential reviewers, please be sure to tell the author not to @-tag their suggestions. + +**Step 7: Editor tells EditorialBot to assign the reviewers to the paper** + +- Use `@editorialbot add @reviewer as reviewer` +- To add a second reviewer use `@editorialbot add @reviewer2 as reviewer` + +**Step 8: Create the actual review issue** + +- Use `@editorialbot start review` +- An issue is created with the review checklist, one per reviewer, e.g. https://github.com/openjournals/joss-reviews/issues/717 + +**Step 9: Close the pre-review issue** + +**Step 10: The actual JOSS review** + +- The reviewer reviews the paper and has a conversation with the author. The editor lurks on this conversation and comes in if needed for questions (or CoC issues). +- The reviewer potentially asks for changes and the author makes changes. Everyone agrees it’s ready. + +**Step 11: The editor pings the EiC team to get the paper published** + +- Make a final check of the paper with `@editorialbot generate pdf` and that all references have DOIs (where appropriate) with `@editorialbot check references`. +- If everything looks good, ask the author to make a new release (if possible) of the software being reviewed and deposit a new archive the software with Zenodo/figshare. Update the review thread with this archive DOI: `@editorialbot set 10.5281/zenodo.xxxxxx as archive`. +- Editors can get a checklist of the final steps using the `@editorialbot create post-review checklist` command +- Finally, use `@editorialbot recommend-accept` on the review thread to ping the `@openjournals/joss-eics` team letting them know the paper is ready to be accepted. + +**Step 12: Celebrate publication! Tweet! Thank reviewers! Say thank you on issue.** + +### Visualization of editorial flow + +![Editorial flow](images/JOSS-flowchart.png) + + ## Pre-review Once a submission comes in, it will be in the queue for a quick check by the Track Editor-in-chief (TEiC). From there, it moves to a `PRE-REVIEW` issue, where the TEiC will assign a handling editor, and the author can suggest reviewers. Initial direction to the authors for improving the paper can already happen here, especially if the paper lacks some requested sections. @@ -89,7 +150,7 @@ Sometimes you'll need to add a new reviewer once the main review (i.e. post pre- - The new reviewer must use the command `@editorialbot generate my checklist` to get a checklist. -## After reviewers recommend acceptance +## Post-review When a submission is ready to be accepted, we ask that the authors issue a new tagged release of the software (if changed), and archive it (on [Zenodo](https://zenodo.org/), [fig**share**](https://figshare.com/), or other). The authors then post the version number and archive DOI in the `REVIEW` issue. The handling editor executes the pre-publication steps, and pings the Track Editor-in-Chief for final processing. @@ -110,7 +171,23 @@ At this point, the EiC/AEiC will take over to make final checks and publish the It’s also a good idea to ask the authors to check the proof. We’ve had a few papers request a post-publication change of author list, for example—this requires a manual download/compile/deposit cycle and should be a rare event. -## Handling of papers published together with AAS publishing + +## Rejecting a paper + +If you believe a submission should be rejected, for example, because it is out of scope for JOSS, then you should: + +- Ask EditorialBot to flag the submission as potentially out of scope with the command `@editorialbot query scope`. This command adds the `query-scope` label to the issue. +- Mention to the author your reasons for flagging the submission as possibly out of scope, and _optionally_ give them an opportunity to defend their submission. +- During the scope review process, the editorial team may ask the authors to provide additional information about their submission to assist the editorial board with their decision. +- The TEiC will make a final determination of whether a submission is in scope, taking into account the feedback of other editors. + +**Scope reviews for resubmissions** + +In the event that an author re-submits a paper to JOSS that was previously rejected, the TEiC will use their discretion to determine: 1) whether a full scope review by the entire editorial team is necessary, 2) if the previous reasons for rejection remain valid, or 3) if there have been enough updates to warrant sending the submission out for review. + +## JOSS Collaborations + +### AAS publishing JOSS is collaborating with [AAS publishing](https://journals.aas.org/) to offer software review for some of the papers submitted to their journals. A detailed overview of the motivations/background is available in the [announcement blog post](https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing), here we document the additional editorial steps that are necessary for JOSS to follow: @@ -122,7 +199,7 @@ JOSS is collaborating with [AAS publishing](https://journals.aas.org/) to offer **After the paper has been accepted by JOSS** - Once the JOSS review is complete, ask the author for the status of their AAS publication, specifically if they have the AAS paper DOI yet. -- Once this is available, ask the author to add this information to their `paper.md` YAML header as documented in the [submission guidelines](submitting.md#what-should-my-paper-contain). +- Once this is available, ask the author to add this information to their `paper.md` YAML header as documented in the [submission guidelines](paper.md#what-should-my-paper-contain). ``` # Optional fields if submitting to a AAS journal too, see this blog post: @@ -137,7 +214,7 @@ aas-journal: Astrophysical Journal <- The name of the AAS journal. - Ask the EiC on rotation to publish the paper as normal (by tagging `@openjournals/joss-eics`). -## Processing of rOpenSci-reviewed or pyOpenSci-reviewed and accepted submissions +### rOpenSci-reviewed or pyOpenSci-reviewed and accepted submissions If a paper has already been reviewed and accepted by rOpenSci or pyOpenSci, the streamlined JOSS review process is: @@ -150,395 +227,7 @@ If a paper has already been reviewed and accepted by rOpenSci or pyOpenSci, the - Go to to the source code repo and grab the Zenodo DOI - Accept and publish the paper -## Rejecting a paper - -If you believe a submission should be rejected, for example, because it is out of scope for JOSS, then you should: - -- Ask EditorialBot to flag the submission as potentially out of scope with the command `@editorialbot query scope`. This command adds the `query-scope` label to the issue. -- Mention to the author your reasons for flagging the submission as possibly out of scope, and _optionally_ give them an opportunity to defend their submission. -- During the scope review process, the editorial team may ask the authors to provide additional information about their submission to assist the editorial board with their decision. -- The TEiC will make a final determination of whether a submission is in scope, taking into account the feedback of other editors. - -**Scope reviews for resubmissions** - -In the event that an author re-submits a paper to JOSS that was previously rejected, the TEiC will use their discretion to determine: 1) whether a full scope review by the entire editorial team is necessary, 2) if the previous reasons for rejection remain valid, or 3) if there have been enough updates to warrant sending the submission out for review. - -### Voting on papers flagged as potentially out of scope - -Once per week, an email is sent to all JOSS editors with a summary of the papers that are currently flagged as potentially out of scope. Editors are asked to review these submissions and vote on the JOSS website if they have an opinion about a submission. - -```{important} -Your input (vote) on submissions that are undergoing a scope review is incredibly valuable to the EiC team. Please try and vote early, and often! -``` - -## Sample messages for authors and reviewers - -### Sample email to potential reviewers - -``` -Dear Dr. Jekyll, - -I found you following links from the page of The Super Project and/or on Twitter. This -message is to ask if you can help us out with a submission to JOSS (The Journal of Open -Source Software, https://joss.theoj.org), where I’m an editor. - -JOSS publishes articles about open source research software. The submission I'd like you -to review is titled: "great software name here" - -and the submission repository is at: https://github.com/< … > - -JOSS is a free, open-source, community driven and developer-friendly online journal -(no publisher is seeking to raise revenue from the volunteer labor of researchers!). - -The review process at JOSS is unique: it takes place in a GitHub issue, is open, -and author-reviewer-editor conversations are encouraged. - -JOSS reviews involve downloading and installing the software, and inspecting the repository -and submitted paper for key elements. See https://joss.readthedocs.io/en/latest/review_criteria.html - -Editors and reviewers post comments on the Review issue, and authors respond to the comments -and improve their submission until acceptance (or withdrawal, if they feel unable to -satisfy the review). - -Would you be able to review this submission for JOSS? If not, can you recommend -someone from your team to help out? - -Kind regards, - -JOSS Editor. -``` - -### Query scope of submission - -``` -:wave: thanks for your submission to JOSS. From a quick inspection of this submission it's not entirely obvious that it meets our [submission criteria](https://joss.readthedocs.io/en/latest/submitting.html#submission-requirements). In particular, this item: - -> - Your software should have an obvious research application - -Could you confirm here that there _is_ a research application for this software (and explain what that application is)? The section [_'what should my paper contain'_](https://joss.readthedocs.io/en/latest/submitting.html#what-should-my-paper-contain) has some guidance for the sort of content we're looking to be present in the `paper.md`. - -Many thanks! -``` - -### GitHub invite to potential reviewers - -``` -:wave: @reviewer1 & @reviewer2, would any of you be willing to review this submission for JOSS? We carry out our checklist-driven reviews here in GitHub issues and follow these guidelines: https://joss.readthedocs.io/en/latest/review_criteria.html -``` - -### Message to reviewers at the start of a review - -``` -👋🏼 @authorname @reviewer1 @reviewer2 this is the review thread for the paper. All of our communications will happen here from now on. - -As a reviewer, the first step is to create a checklist for your review by entering - -```@editorialbot generate my checklist``` - -as the top of a new comment in this thread. - -These checklists contain the JOSS requirements. As you go over the submission, please check any items that you feel have been satisfied. The first comment in this thread also contains links to the JOSS reviewer guidelines. - -The JOSS review is different from most other journals. Our goal is to work with the authors to help them meet our criteria instead of merely passing judgment on the submission. As such, the reviewers are encouraged to submit issues and pull requests on the software repository. When doing so, please mention `openjournals/joss-reviews#REVIEW_NUMBER` so that a link is created to this thread (and I can keep an eye on what is happening). Please also feel free to comment and ask questions on this thread. In my experience, it is better to post comments/questions/suggestions as you come across them instead of waiting until you've reviewed the entire package. - -We aim for reviews to be completed within about 2-4 weeks. Please let me know if any of you require some more time. We can also use EditorialBot (our bot) to set automatic reminders if you know you'll be away for a known period of time. - -Please feel free to ping me (@editorname) if you have any questions/concerns. -``` - -### Message to authors at the end of a review - -``` -At this point could you: -- Make a tagged release of your software, and list the version tag of the archived version here. -- Archive the reviewed software in Zenodo or a similar service (e.g., figshare, an institutional repository) -- Check the archival deposit (e.g., in Zenodo) has the correct metadata. This includes the title (should match the paper title) and author list (make sure the list is correct and people who only made a small fix are not on it). You may also add the authors' ORCID. -- Please list the DOI of the archived version here. - -I can then move forward with recommending acceptance of the submission. -``` - -### Rejection due to out of scope/failing substantial scholarly effort test - -(Note that rejections are handled by EiCs and not individual editors). - -``` -@authorname - thanks for your submission to JOSS. Unfortunately, after review by the JOSS editorial team we've determined that this submission doesn't meet our [substantial scholarly effort](https://joss.readthedocs.io/en/latest/submitting.html#substantial-scholarly-effort) criterion. - -One possible alternative to JOSS is to follow [GitHub's guide](https://guides.github.com/activities/citable-code/) on how to create a permanent archive and DOI for your software. This DOI can then be used by others to cite your work. -``` - -## Overview of editorial process - -**Step 1: An author submits a paper.** - -The author can choose to select an preferred editor based on the information available in our biographies. This can be changed later. - -**Step 2: If you are selected as an editor you get @-mentioned in the pre-review issue.** - -This doesn’t mean that you’re the editor, just that you’ve been suggested by the author. - -**Step 3: Once you are the editor, find the link to the code repository in the `pre-review` issue** - -- If the paper is not in the default branch, add it to the issue with the command: `@editorialbot set branch-where-paper-is as branch`. - -**Step 4: The editor looks at the software submitted and checks to see if:** - -- There’s a general description of the software -- The software is within scope as research software -- It has an OSI-approved license - -**Step 5: The editor responds to the author saying that things look in line (or not) and will search for reviewer** - -**Step 6: The editor finds >= 2 reviewers** - -- Use the list of reviewers: type the command `@editorialbot list reviewers` or - look at use the [Reviewers Management System](https://reviewers.joss.theoj.org) -- If people are in the review list, the editor can @-mention them on the issue to see if they will review: e.g. `@person1 @person2 can you review this submission for JOSS?` -- Or solicit reviewers outside the list. Send an email to people describing what JOSS is and asking if they would be interested in reviewing. -- If you ask the author to suggest potential reviewers, please be sure to tell the author not to @-tag their suggestions. - -**Step 7: Editor tells EditorialBot to assign the reviewers to the paper** - -- Use `@editorialbot add @reviewer as reviewer` -- To add a second reviewer use `@editorialbot add @reviewer2 as reviewer` - -**Step 8: Create the actual review issue** - -- Use `@editorialbot start review` -- An issue is created with the review checklist, one per reviewer, e.g. https://github.com/openjournals/joss-reviews/issues/717 - -**Step 9: Close the pre-review issue** - -**Step 10: The actual JOSS review** - -- The reviewer reviews the paper and has a conversation with the author. The editor lurks on this conversation and comes in if needed for questions (or CoC issues). -- The reviewer potentially asks for changes and the author makes changes. Everyone agrees it’s ready. - -**Step 11: The editor pings the EiC team to get the paper published** - -- Make a final check of the paper with `@editorialbot generate pdf` and that all references have DOIs (where appropriate) with `@editorialbot check references`. -- If everything looks good, ask the author to make a new release (if possible) of the software being reviewed and deposit a new archive the software with Zenodo/figshare. Update the review thread with this archive DOI: `@editorialbot set 10.5281/zenodo.xxxxxx as archive`. -- Editors can get a checklist of the final steps using the `@editorialbot create post-review checklist` command -- Finally, use `@editorialbot recommend-accept` on the review thread to ping the `@openjournals/joss-eics` team letting them know the paper is ready to be accepted. - -**Step 12: Celebrate publication! Tweet! Thank reviewers! Say thank you on issue.** - -## Visualization of editorial flow - -![Editorial flow](images/JOSS-flowchart.png) - -## Expectations on JOSS editors - -### Editorial load - -Our goal is for editors to handle between 3-4 submissions at any one time, and 8-12 submissions per year. During the trial period for editors (usually the first 90 days), we recommend new editors handle 1-2 submissions as they learn the JOSS editorial system and processes. - -### Completing the trial period - -JOSS has a 90-day trial period for new editors. At the end of the trial, the editor or JOSS editorial board can decide to part ways if either party determines editing for JOSS isn't a good fit for the editor. The most important traits the editorial board will be looking for with new editors are: - -- Demonstrating professionalism in communications with authors, reviewers, and the wider editorial team. -- Editorial responsibility, including [keeping up with their assigned submissions](#continued-attention-to-assigned-submissions). -- Encouraging good social (software community) practices. For example, thanking reviewers and making them feel like they are part of a team working together. - -If you're struggling with your editorial work, please let your buddy or an EiC know. - -### Responding to editorial assignments - -As documented above, usually, papers will be assigned to you by one of the TEiCs. We ask that editors do their best to respond in a timely fashion (~ 3 working days) to invites to edit a new submission. - -### Continued attention to assigned submissions - -As an editor, part of your role is to ensure that submissions you're responsible for are progressing smoothly through the editorial process. This means that: - -- During pre-review, and before reviewers have been identified, editors should be checking on their submissions twice per week to ensure reviewers are identified in a timely fashion. -- During review, editors should check on their submissions once or twice per week (even for just a few minutes) to see if their input is required (e.g., if someone has asked a question that requires your input). - -Your editorial dashboard (e.g. `https://joss.theoj.org/dashboard/youreditorname`) is the best place to check if there have been any updates to the papers you are editing. - -**If reviews go stale** - -Sometimes reviews go quiet, either because a reviewer has failed to complete their review or an author has been slow to respond to a reviewer's feedback. **As the editor, we need you to prompt the author/or reviewer(s) to revisit the submission if there has been no response within 7-10 days unless there's a clear statement in the review thread that says an action is coming at a slightly later time, perhaps because a reviewer committed to a review by a certain date, or an author is making changes and says they will be done by a certain date.** - -[EditorialBot has functionality](https://joss.readthedocs.io/en/latest/editorial_bot.html#reminding-reviewers-and-authors) to remind an author or review to return to a review at a certain point in the future. For example: - -``` -@editorialbot remind @reviewer in five days -``` - -## Out of office - -Sometimes we need time away from our editing duties at JOSS. If you're planning on being out of the office for more than two weeks, please let the JOSS editorial team know. - -## Editorial buddy - -New editors are assigned an editorial 'buddy' from the existing editorial team. The buddy is there to help the new editor onboard successfully and to provide a dedicated resource for any questions they might have but don't feel comfortable posting to the editor mailing list. - -Buddy assignments don't have a fixed term but generally require a commitment for 1-2 months. - -Some things you might need to do as a buddy for a new editor: - -- Respond to questions via email or on GitHub review issues. -- Check in with the new editor every couple of weeks if there hasn't been any other communication. -- (Optionally) keep an eye on the new editor's submissions. - -## Managing notifications - -Being on the JOSS editorial team means that there can be a _lot_ of notifications from GitHub if you don't take some proactive steps to minimize noise from the reviews repository. - -### Things you should do when joining the editorial team - -**Curate your GitHub notifications experience** - -GitHub has extensive documentation on [managing notifications](https://help.github.com/en/articles/managing-your-notifications) which explains when and why different notifications are sent from a repository. - -**Set up email filters** - -Email filters can be very useful for managing incoming email notifications, here are some recommended resources: - -- A GitHub blog post describing how to set up [email filters](https://github.blog/2017-07-18-managing-large-numbers-of-github-notifications/). - -If you use Gmail: - -- https://gist.github.com/ldez/bd6e6401ad0855e6c0de6da19a8c50b5 -- https://github.com/jessfraz/gmailfilters -- https://hackernoon.com/how-to-never-miss-a-github-mention-fdd5a0f9ab6d - -**Use a dedicated tool** - -For papers that you are already assigned to edit, the dedicated JOSS dashboard aggregates notifications associated with each paper. The dashboard is available at: `https://joss.theoj.org/dashboard/` - -Another tool you might want to try out is [Octobox](https://octobox.io/). - -## Top tips for JOSS editors - -**Aim for reviewer redundancy** - -If you have 3 people agree to review, take them up on their offer(s), that way if one person drops out, you'll have a backup and won't have to look for more reviewers. Also, when sending invites, try pinging a number of people at the same time rather than doing it one-by-one. - -**Email is a good backup** - -Email is often the most reliable way of contacting people. Whether it's inviting reviewers, following up with reviewers or authors etc., if you've not heard back from someone on GitHub, try emailing them (their email is often available on their GitHub profile page). - -**Default to over-communicating** - -When you take an action (even if it isn't on GitHub), share on the review thready what you're up to. For example, if you're looking for reviewers and are sending emails – leave a note on the review thread saying as much. - -**Use the JOSS Slack** - -There's lots of historical knowledge in our Slack, and it's a great way to get questions answered. - -**Ask reviewers to complete their review in 4-6 weeks** - -We aim for a total submission ... publication time of ~3 months. This means we ideally want reviewers to complete their review in 4-6 weeks (max). - -**Use saved replies on GitHub** - -[Saved replies](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies/using-saved-replies) on GitHub can be a huge productivity boost. Try making some using the example messages listed above. - -**Ping reviewers if they’ve not started after 2 weeks** - -If a reviewer hasn't started within 1-2 weeks, you should probably give them a nudge. People often agree to review, and then forget about the review. - -**Learn how to nudge gently, and often** - -One of your jobs as the editor is to ensure the review keeps moving at a reasonable pace. If nothing has happened for a week or so, consider nudging the author or reviewers (depending upon who you're waiting for). A friendly _"👋 reviewer, how are you getting along here"_ can often be sufficient to get things moving again. - -**Check in twice a week** - -Try to check in on your JOSS submissions twice per week, even if only for 5 minutes. Use your dashboard to stay on top of the current status of your submissions (i.e., who was the last person to comment on the thread). - -**Leave feedback on reviewers** - -Leave feedback on the [reviewers application](https://reviewers.joss.theoj.org/) at the end of the review. This helps future editors when they're seeking out good reviewer candidates. - -## Onboarding a new JOSS editor - -All new editors at JOSS have an onboarding call with an Editor-in-Chief. You can use the structure below to make sure you highlight the most important aspects of being an editor. - -**Thing to check before the call** - -- Have they reviewed or published in JOSS before? If not, you'll need to spend significantly more time explaining how the review process works. -- Check on their research background (e.g., what tracks they might edit most actively in). -- Make sure to send them the [editorial guide](https://joss.readthedocs.io/en/latest/editing.html) to read before the call. - -### The onboarding call - -**Preamble/introductions** - -- Welcome! Thank them for their application to join the team. -- Point out that this isn't an interview. Rather, this is an informational call designed to give the candidate the information they need to make an informed decision about editing at JOSS. -- 90-day trial period/try out. Editor or JOSS editorial board can decide to part ways after that period. -- No strict term limits. Some editors have been with us for 7+ years, others do 1-2 years. Most important thing is to be proactive with your editing responsibilities and communicating any issues with the EiCs. -- Confirm with them their level of familiarity with JOSS/our review process. -- Point out that they *do not* need to make a decision on the call today. They are welcome to have a think about joining and get back to us. - -**Share your screen** - -- Visit JOSS (https://joss.theoj.org) -- Pick a recently-published paper (you might want to identify this before the call one that shows off the review process well). -- Show the paper on the JOSS site, and then go to the linked review issue. -- Explain that there are *two* issues per submission – the pre-review issue and the main review issue. - -**The pre-review issue** - -- The 'meeting room for the paper'. Where author meets editor, and reviewers are identified. -- Note that the EiC may have initiated a scope review. The editor should not start editing until this has completed. Also, editors are able to query the scope (as are reviewers) if they think the EiC should have (but didn't). -- Walk them through what is happening in the pre-review issue... -- Editor is invited (likely with GitHub mention but also via email invite (`@editorialbot invite @editor as editor`)) -- Once editor accepts they start looking for reviewers. - -**Finding reviewers** - -- Explain that this is one of the more time-intensive aspects of editing. -- Explain where you can look for editors (your own professional network, asking the authors for recommendations, the [reviewers application](https://reviewers.joss.theoj.org/), similar papers identified by Editorialbot, ) -- Point out that we have a minimum of two reviewers, but if more than that accept (e.g., 3/4 then take them all – this gives you redundancy if one drops out). -- Don't invite only one reviewer at a time! If you do this, it may take many weeks to find two reviewers who accept. Try 3/4/5 invites simultaneously. -- The [sample messages](#sample-messages-for-authors-and-reviewers) section of the documentation has some example language you can use. - -**The review** - -- Once at least two reviewers are assigned, time to get going! -- Encourage reviewers to complete their review in 4-6 weeks. -- Make sure to check in on the review – if reviewers haven't started after ~1-2 weeks, time to remind them. -- Your role as editor is not to do the review yourself, rather, your job is to ensure that both reviewers give a good review and to facilitate discussion and consensus on what the author needs to do. -- Walk the editor through the various review artifacts: The checklist, comments/questions/discussion between reviewers and author, issues opened on the upstream repository (and cross-linked into the review thread). -- Point editors to the ['top tips'](#top-tips-for-joss-editors) section of our docs. Much of what makes an editor successful is regular check-ins on the review, and nudging people if nothing is happening. -- Do *not* let a review go multiple weeks without checking in. - -**Wrapping up the review** - -- Once the review is wrapping up, show the candidate the checks that an editor should be doing (reading the paper, suggested edits, asking for an archive etc.) -- Show the `recommend-accept` step which is the formal hand-off between editor and editor-in-chief. -- The [sample messages](#sample-messages-for-authors-and-reviewers) section of the documentation has a checklist for the last steps of the review (for both authors and editors). - - -**Show them the dashboard on the JOSS site** - -- Point out that this means you *do not* need to stay on top of all of your notifications (the dashboard has the latest information). -- Highlight here that we ask editors to handle 8-12 submissions per year on average. -- ...and that means 3-4 submissions on their desk at any one time (once they have completed their initial probationary period). -- Show them the backlog for a track, and how they are welcome to pick papers from it (ideally oldest first). -- Show them their profile page, and how they can list their tracks there, and also what their availability is. - -**Other important things to highlight** - -- Don't invite other editors as reviewers. We're all busy editing our own papers... -- Please be willing to edit outside of your specialisms. This helps JOSS run smoothly – often we don't have the 'ideal' editor for a submission and someone has to take it. -- Highlight that editors will have a buddy to work with for the first few months, and that it's very common for editors to ask questions in Slack (and people generally respond quickly). -- Scope reviews only work if editors vote! Please respond and vote on the weekly scope review email if you can. The process is private (authors don't know what editors are saying). Detailed comments are really helpful for the EiCs. -**Wrapping up** -- Make sure you've highlighted everything in the ['top tips'](#top-tips-for-joss-editors) section of our docs. -- Reinforce that this is a commitment, and thay regular attention to their submissions is absolutely critical (i.e., check in a couple of times per week). -- Ask if they would like to move forward or would like time to consider the opportunity. -- If they want to move forward, highlight they will receive a small number of invites: One to the JOSS editors GitHub team, a Slack invite, a Google Group invite, and an invite to the JOSS website to fill out their profile. -- Thank them again, and welcome them to the team. -**Communicate outcome to EiC** -- Let the EiC know what the outcome was, and ask them to send out the invites to our various systems. -- Work with EiC to identify onboarding buddy. -- Decide who is going to identify the first couple of papers for the editor to work on. diff --git a/docs/editor_onboarding.md b/docs/editor_onboarding.md new file mode 100644 index 00000000..3d86aaef --- /dev/null +++ b/docs/editor_onboarding.md @@ -0,0 +1,131 @@ +# Editor Onboarding + +## Onboarding a new JOSS editor + +All new editors at JOSS have an onboarding call with an Editor-in-Chief. You can use the structure below to make sure you highlight the most important aspects of being an editor. + +**Thing to check before the call** + +- Have they reviewed or published in JOSS before? If not, you'll need to spend significantly more time explaining how the review process works. +- Check on their research background (e.g., what tracks they might edit most actively in). +- Make sure to send them the [editorial guide](https://joss.readthedocs.io/en/latest/editing.html) to read before the call. + +### The onboarding call + +**Preamble/introductions** + +- Welcome! Thank them for their application to join the team. +- Point out that this isn't an interview. Rather, this is an informational call designed to give the candidate the information they need to make an informed decision about editing at JOSS. +- 90-day trial period/try out. Editor or JOSS editorial board can decide to part ways after that period. +- No strict term limits. Some editors have been with us for 7+ years, others do 1-2 years. Most important thing is to be proactive with your editing responsibilities and communicating any issues with the EiCs. +- Confirm with them their level of familiarity with JOSS/our review process. +- Point out that they *do not* need to make a decision on the call today. They are welcome to have a think about joining and get back to us. + +**Share your screen** + +- Visit JOSS (https://joss.theoj.org) +- Pick a recently-published paper (you might want to identify this before the call one that shows off the review process well). +- Show the paper on the JOSS site, and then go to the linked review issue. +- Explain that there are *two* issues per submission – the pre-review issue and the main review issue. + +**The pre-review issue** + +- The 'meeting room for the paper'. Where author meets editor, and reviewers are identified. +- Note that the EiC may have initiated a scope review. The editor should not start editing until this has completed. Also, editors are able to query the scope (as are reviewers) if they think the EiC should have (but didn't). +- Walk them through what is happening in the pre-review issue... +- Editor is invited (likely with GitHub mention but also via email invite (`@editorialbot invite @editor as editor`)) +- Once editor accepts they start looking for reviewers. + +**Finding reviewers** + +- Explain that this is one of the more time-intensive aspects of editing. +- Explain where you can look for editors (your own professional network, asking the authors for recommendations, the [reviewers application](https://reviewers.joss.theoj.org/), similar papers identified by Editorialbot, ) +- Point out that we have a minimum of two reviewers, but if more than that accept (e.g., 3/4 then take them all – this gives you redundancy if one drops out). +- Don't invite only one reviewer at a time! If you do this, it may take many weeks to find two reviewers who accept. Try 3/4/5 invites simultaneously. +- The [sample messages](sample_messages) section of the documentation has some example language you can use. + +**The review** + +- Once at least two reviewers are assigned, time to get going! +- Encourage reviewers to complete their review in 4-6 weeks. +- Make sure to check in on the review – if reviewers haven't started after ~1-2 weeks, time to remind them. +- Your role as editor is not to do the review yourself, rather, your job is to ensure that both reviewers give a good review and to facilitate discussion and consensus on what the author needs to do. +- Walk the editor through the various review artifacts: The checklist, comments/questions/discussion between reviewers and author, issues opened on the upstream repository (and cross-linked into the review thread). +- Point editors to the ['top tips'](editor_tips) section of our docs. Much of what makes an editor successful is regular check-ins on the review, and nudging people if nothing is happening. +- Do *not* let a review go multiple weeks without checking in. + +**Wrapping up the review** + +- Once the review is wrapping up, show the candidate the checks that an editor should be doing (reading the paper, suggested edits, asking for an archive etc.) +- Show the `recommend-accept` step which is the formal hand-off between editor and editor-in-chief. +- The [sample messages](sample_messages) section of the documentation has a checklist for the last steps of the review (for both authors and editors). + + +**Show them the dashboard on the JOSS site** + +- Point out that this means you *do not* need to stay on top of all of your notifications (the dashboard has the latest information). +- Highlight here that we ask editors to handle 8-12 submissions per year on average. +- ...and that means 3-4 submissions on their desk at any one time (once they have completed their initial probationary period). +- Show them the backlog for a track, and how they are welcome to pick papers from it (ideally oldest first). +- Show them their profile page, and how they can list their tracks there, and also what their availability is. + +**Other important things to highlight** + +- Don't invite other editors as reviewers. We're all busy editing our own papers... +- Please be willing to edit outside of your specialisms. This helps JOSS run smoothly – often we don't have the 'ideal' editor for a submission and someone has to take it. +- Highlight that editors will have a buddy to work with for the first few months, and that it's very common for editors to ask questions in Slack (and people generally respond quickly). +- Scope reviews only work if editors vote! Please respond and vote on the weekly scope review email if you can. The process is private (authors don't know what editors are saying). Detailed comments are really helpful for the EiCs. + +**Wrapping up** + +- Make sure you've highlighted everything in the ['top tips'](editor_tips) section of our docs. +- Reinforce that this is a commitment, and thay regular attention to their submissions is absolutely critical (i.e., check in a couple of times per week). +- Ask if they would like to move forward or would like time to consider the opportunity. +- If they want to move forward, highlight they will receive a small number of invites: One to the JOSS editors GitHub team, a Slack invite, a Google Group invite, and an invite to the JOSS website to fill out their profile. +- Thank them again, and welcome them to the team. + +**Communicate outcome to EiC** + +- Let the EiC know what the outcome was, and ask them to send out the invites to our various systems. +- Work with EiC to identify onboarding buddy. +- Decide who is going to identify the first couple of papers for the editor to work on. + +## Editorial buddy + +New editors are assigned an editorial 'buddy' from the existing editorial team. The buddy is there to help the new editor onboard successfully and to provide a dedicated resource for any questions they might have but don't feel comfortable posting to the editor mailing list. + +Buddy assignments don't have a fixed term but generally require a commitment for 1-2 months. + +Some things you might need to do as a buddy for a new editor: + +- Respond to questions via email or on GitHub review issues. +- Check in with the new editor every couple of weeks if there hasn't been any other communication. +- (Optionally) keep an eye on the new editor's submissions. + +## Managing notifications + +Being on the JOSS editorial team means that there can be a _lot_ of notifications from GitHub if you don't take some proactive steps to minimize noise from the reviews repository. + +### Things you should do when joining the editorial team + +**Curate your GitHub notifications experience** + +GitHub has extensive documentation on [managing notifications](https://help.github.com/en/articles/managing-your-notifications) which explains when and why different notifications are sent from a repository. + +**Set up email filters** + +Email filters can be very useful for managing incoming email notifications, here are some recommended resources: + +- A GitHub blog post describing how to set up [email filters](https://github.blog/2017-07-18-managing-large-numbers-of-github-notifications/). + +If you use Gmail: + +- https://gist.github.com/ldez/bd6e6401ad0855e6c0de6da19a8c50b5 +- https://github.com/jessfraz/gmailfilters +- https://hackernoon.com/how-to-never-miss-a-github-mention-fdd5a0f9ab6d + +**Use a dedicated tool** + +For papers that you are already assigned to edit, the dedicated JOSS dashboard aggregates notifications associated with each paper. The dashboard is available at: `https://joss.theoj.org/dashboard/` + +Another tool you might want to try out is [Octobox](https://octobox.io/). \ No newline at end of file diff --git a/docs/editor_tips.md b/docs/editor_tips.md new file mode 100644 index 00000000..06308d60 --- /dev/null +++ b/docs/editor_tips.md @@ -0,0 +1,41 @@ +# Top tips for JOSS editors + +**Aim for reviewer redundancy** + +If you have 3 people agree to review, take them up on their offer(s), that way if one person drops out, you'll have a backup and won't have to look for more reviewers. Also, when sending invites, try pinging a number of people at the same time rather than doing it one-by-one. + +**Email is a good backup** + +Email is often the most reliable way of contacting people. Whether it's inviting reviewers, following up with reviewers or authors etc., if you've not heard back from someone on GitHub, try emailing them (their email is often available on their GitHub profile page). + +**Default to over-communicating** + +When you take an action (even if it isn't on GitHub), share on the review thready what you're up to. For example, if you're looking for reviewers and are sending emails – leave a note on the review thread saying as much. + +**Use the JOSS Slack** + +There's lots of historical knowledge in our Slack, and it's a great way to get questions answered. + +**Ask reviewers to complete their review in 4-6 weeks** + +We aim for a total submission ... publication time of ~3 months. This means we ideally want reviewers to complete their review in 4-6 weeks (max). + +**Use saved replies on GitHub** + +[Saved replies](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies/using-saved-replies) on GitHub can be a huge productivity boost. Try making some using the example messages listed above. + +**Ping reviewers if they’ve not started after 2 weeks** + +If a reviewer hasn't started within 1-2 weeks, you should probably give them a nudge. People often agree to review, and then forget about the review. + +**Learn how to nudge gently, and often** + +One of your jobs as the editor is to ensure the review keeps moving at a reasonable pace. If nothing has happened for a week or so, consider nudging the author or reviewers (depending upon who you're waiting for). A friendly _"👋 reviewer, how are you getting along here"_ can often be sufficient to get things moving again. + +**Check in twice a week** + +Try to check in on your JOSS submissions twice per week, even if only for 5 minutes. Use your dashboard to stay on top of the current status of your submissions (i.e., who was the last person to comment on the thread). + +**Leave feedback on reviewers** + +Leave feedback on the [reviewers application](https://reviewers.joss.theoj.org/) at the end of the review. This helps future editors when they're seeking out good reviewer candidates. \ No newline at end of file diff --git a/docs/example_paper.md b/docs/example_paper.md new file mode 100644 index 00000000..6ab7e5ac --- /dev/null +++ b/docs/example_paper.md @@ -0,0 +1,194 @@ +# Example Paper + +This example `paper.md` is adapted from _Gala: A Python package for galactic dynamics_ by Adrian M. Price-Whelan [http://doi.org/10.21105/joss.00388](http://doi.org/10.21105/joss.00388). + +For a complete description of available options to describe author names [see here](author-names). + +```markdown +--- +title: 'Gala: A Python package for galactic dynamics' +tags: + - Python + - astronomy + - dynamics + - galactic dynamics + - milky way +authors: + - name: Adrian M. Price-Whelan + orcid: 0000-0000-0000-0000 + equal-contrib: true + affiliation: "1, 2" # (Multiple affiliations must be quoted) + - name: Author Without ORCID + equal-contrib: true # (This is how you can denote equal contributions between multiple authors) + affiliation: 2 + - name: Author with no affiliation + corresponding: true # (This is how to denote the corresponding author) + affiliation: 3 + - given-names: Ludwig + dropping-particle: van + surname: Beethoven + affiliation: 3 +affiliations: + - name: Lyman Spitzer, Jr. Fellow, Princeton University, USA + index: 1 + - name: Institution Name, Country + index: 2 + - name: Independent Researcher, Country + index: 3 +date: 13 August 2017 +bibliography: paper.bib + +# Optional fields if submitting to a AAS journal too, see this blog post: +# https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing +aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it. +aas-journal: Astrophysical Journal <- The name of the AAS journal. +--- + +# Summary + +The forces on stars, galaxies, and dark matter under external gravitational +fields lead to the dynamical evolution of structures in the universe. The orbits +of these bodies are therefore key to understanding the formation, history, and +future state of galaxies. The field of "galactic dynamics," which aims to model +the gravitating components of galaxies to study their structure and evolution, +is now well-established, commonly taught, and frequently used in astronomy. +Aside from toy problems and demonstrations, the majority of problems require +efficient numerical tools, many of which require the same base code (e.g., for +performing numerical orbit integration). + +# Statement of need + +`Gala` is an Astropy-affiliated Python package for galactic dynamics. Python +enables wrapping low-level languages (e.g., C) for speed without losing +flexibility or ease-of-use in the user-interface. The API for `Gala` was +designed to provide a class-based and user-friendly interface to fast (C or +Cython-optimized) implementations of common operations such as gravitational +potential and force evaluation, orbit integration, dynamical transformations, +and chaos indicators for nonlinear dynamics. `Gala` also relies heavily on and +interfaces well with the implementations of physical units and astronomical +coordinate systems in the `Astropy` package [@astropy] (`astropy.units` and +`astropy.coordinates`). + +`Gala` was designed to be used by both astronomical researchers and by +students in courses on gravitational dynamics or astronomy. It has already been +used in a number of scientific publications [@Pearson:2017] and has also been +used in graduate courses on Galactic dynamics to, e.g., provide interactive +visualizations of textbook material [@Binney:2008]. The combination of speed, +design, and support for Astropy functionality in `Gala` will enable exciting +scientific explorations of forthcoming data releases from the *Gaia* mission +[@gaia] by students and experts alike. + +# Mathematics + +Single dollars ($) are required for inline mathematics e.g. $f(x) = e^{\pi/x}$ + +Double dollars make self-standing equations: + +$$\Theta(x) = \left\{\begin{array}{l} +0\textrm{ if } x < 0\cr +1\textrm{ else} +\end{array}\right.$$ + +You can also use plain \LaTeX for equations +\begin{equation}\label{eq:fourier} +\hat f(\omega) = \int_{-\infty}^{\infty} f(x) e^{i\omega x} dx +\end{equation} +and refer to \autoref{eq:fourier} from text. + +# Citations + +Citations to entries in paper.bib should be in +[rMarkdown](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html) +format. + +If you want to cite a software repository URL (e.g. something on GitHub without a preferred +citation) then you can do it with the example BibTeX entry below for @fidgit. + +For a quick reference, the following citation commands can be used: +- `@author:2001` -> "Author et al. (2001)" +- `[@author:2001]` -> "(Author et al., 2001)" +- `[@author1:2001; @author2:2001]` -> "(Author1 et al., 2001; Author2 et al., 2002)" + +# Figures + +Figures can be included like this: +![Caption for example figure.\label{fig:example}](figure.png) +and referenced from text using \autoref{fig:example}. + +Figure sizes can be customized by adding an optional second parameter: +![Caption for example figure.](figure.png){ width=20% } + +# Acknowledgements + +We acknowledge contributions from Brigitta Sipocz, Syrtis Major, and Semyeong +Oh, and support from Kathryn Johnston during the genesis of this project. + +# References + +``` + +Example `paper.bib` file: + +``` +@article{Pearson:2017, + url = {http://adsabs.harvard.edu/abs/2017arXiv170304627P}, + Archiveprefix = {arXiv}, + Author = {{Pearson}, S. and {Price-Whelan}, A.~M. and {Johnston}, K.~V.}, + Eprint = {1703.04627}, + Journal = {ArXiv e-prints}, + Keywords = {Astrophysics - Astrophysics of Galaxies}, + Month = mar, + Title = {{Gaps in Globular Cluster Streams: Pal 5 and the Galactic Bar}}, + Year = 2017 +} + +@book{Binney:2008, + url = {http://adsabs.harvard.edu/abs/2008gady.book.....B}, + Author = {{Binney}, J. and {Tremaine}, S.}, + Booktitle = {Galactic Dynamics: Second Edition, by James Binney and Scott Tremaine.~ISBN 978-0-691-13026-2 (HB).~Published by Princeton University Press, Princeton, NJ USA, 2008.}, + Publisher = {Princeton University Press}, + Title = {{Galactic Dynamics: Second Edition}}, + Year = 2008 +} + +@article{gaia, + author = {{Gaia Collaboration}}, + title = "{The Gaia mission}", + journal = {Astronomy and Astrophysics}, + archivePrefix = "arXiv", + eprint = {1609.04153}, + primaryClass = "astro-ph.IM", + keywords = {space vehicles: instruments, Galaxy: structure, astrometry, parallaxes, proper motions, telescopes}, + year = 2016, + month = nov, + volume = 595, + doi = {10.1051/0004-6361/201629272}, + url = {http://adsabs.harvard.edu/abs/2016A%26A...595A...1G}, +} + +@article{astropy, + author = {{Astropy Collaboration}}, + title = "{Astropy: A community Python package for astronomy}", + journal = {Astronomy and Astrophysics}, + archivePrefix = "arXiv", + eprint = {1307.6212}, + primaryClass = "astro-ph.IM", + keywords = {methods: data analysis, methods: miscellaneous, virtual observatory tools}, + year = 2013, + month = oct, + volume = 558, + doi = {10.1051/0004-6361/201322068}, + url = {http://adsabs.harvard.edu/abs/2013A%26A...558A..33A} +} + +@misc{fidgit, + author = {A. M. Smith and K. Thaney and M. Hahnel}, + title = {Fidgit: An ungodly union of GitHub and Figshare}, + year = {2020}, + publisher = {GitHub}, + journal = {GitHub repository}, + url = {https://github.com/arfon/fidgit} +} +``` + +Note that the paper begins by a metadata section (the enclosing --- lines are mandatory) and ends with a References heading, and the references are built automatically from the content in the `.bib` file. You should enter in-text citations in the paper body following correct [Markdown citation syntax](https://pandoc.org/MANUAL.html#extension-citations). Also note that the references include full names of venues, e.g., journals and conferences, not abbreviations only understood in the context of a specific discipline. \ No newline at end of file diff --git a/docs/expectations.md b/docs/expectations.md new file mode 100644 index 00000000..6f1a0175 --- /dev/null +++ b/docs/expectations.md @@ -0,0 +1,50 @@ +# Expectations on JOSS editors + +## Editorial load + +Our goal is for editors to handle between 3-4 submissions at any one time, and 8-12 submissions per year. During the trial period for editors (usually the first 90 days), we recommend new editors handle 1-2 submissions as they learn the JOSS editorial system and processes. + +## Completing the trial period + +JOSS has a 90-day trial period for new editors. At the end of the trial, the editor or JOSS editorial board can decide to part ways if either party determines editing for JOSS isn't a good fit for the editor. The most important traits the editorial board will be looking for with new editors are: + +- Demonstrating professionalism in communications with authors, reviewers, and the wider editorial team. +- Editorial responsibility, including [keeping up with their assigned submissions](#continued-attention-to-assigned-submissions). +- Encouraging good social (software community) practices. For example, thanking reviewers and making them feel like they are part of a team working together. + +If you're struggling with your editorial work, please let your buddy or an EiC know. + +## Responding to editorial assignments + +As documented above, usually, papers will be assigned to you by one of the TEiCs. We ask that editors do their best to respond in a timely fashion (~ 3 working days) to invites to edit a new submission. + +## Continued attention to assigned submissions + +As an editor, part of your role is to ensure that submissions you're responsible for are progressing smoothly through the editorial process. This means that: + +- During pre-review, and before reviewers have been identified, editors should be checking on their submissions twice per week to ensure reviewers are identified in a timely fashion. +- During review, editors should check on their submissions once or twice per week (even for just a few minutes) to see if their input is required (e.g., if someone has asked a question that requires your input). + +Your editorial dashboard (e.g. `https://joss.theoj.org/dashboard/youreditorname`) is the best place to check if there have been any updates to the papers you are editing. + +**If reviews go stale** + +Sometimes reviews go quiet, either because a reviewer has failed to complete their review or an author has been slow to respond to a reviewer's feedback. **As the editor, we need you to prompt the author/or reviewer(s) to revisit the submission if there has been no response within 7-10 days unless there's a clear statement in the review thread that says an action is coming at a slightly later time, perhaps because a reviewer committed to a review by a certain date, or an author is making changes and says they will be done by a certain date.** + +[EditorialBot has functionality](https://joss.readthedocs.io/en/latest/editorial_bot.html#reminding-reviewers-and-authors) to remind an author or review to return to a review at a certain point in the future. For example: + +``` +@editorialbot remind @reviewer in five days +``` + +## Out of office + +Sometimes we need time away from our editing duties at JOSS. If you're planning on being out of the office for more than two weeks, please let the JOSS editorial team know. + +## Voting on papers flagged as potentially out of scope + +Once per week, an email is sent to all JOSS editors with a summary of the papers that are currently flagged as potentially out of scope. Editors are asked to review these submissions and vote on the JOSS website if they have an opinion about a submission. + +```{important} +Your input (vote) on submissions that are undergoing a scope review is incredibly valuable to the EiC team. Please try and vote early, and often! +``` \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index bc289b2e..d6660dc7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,20 +31,31 @@ Sponsors and affiliates JOSS is a proud affiliate of the `Open Source Initiative `_. As such, we are committed to public support for open source software and the role OSI plays therein. In addition, Open Journals (the parent entity behind JOSS) is a `NumFOCUS-sponsored project `_. .. toctree:: - :caption: Author and Reviewer Guides + :caption: Author Guides :maxdepth: 5 submitting + paper + example_paper + policies + +.. toctree:: + :caption: Reviewer Guides + :maxdepth: 5 + reviewer_guidelines review_criteria review_checklist - policies .. toctree:: :caption: Editor Guides :maxdepth: 2 editing + expectations + editor_onboarding + editor_tips + sample_messages .. toctree:: :caption: The Editorial Bot diff --git a/docs/paper.md b/docs/paper.md new file mode 100644 index 00000000..4440a736 --- /dev/null +++ b/docs/paper.md @@ -0,0 +1,366 @@ +# JOSS Paper Format + +Submitted articles must use Markdown and must provide a metadata section at the beginning of the article. Format metadata using YAML, a human-friendly data serialization language (The Official YAML Web Site, 2022). The information provided is included in the title and sidebar of the generated PDF. + +--- + +## What should my paper contain? + +```{important} +Begin your paper with a summary of the high-level functionality of your software for a non-specialist reader. Avoid jargon in this section. +``` + +JOSS welcomes submissions from broadly diverse research areas. For this reason, we require that authors include in the paper some sentences that explain the software functionality and domain of use to a non-specialist reader. We also require that authors explain the research applications of the software. The paper should be between 250-1000 words. Authors submitting papers significantly longer than 1000 words may be asked to reduce the length of their paper. + +Your paper should include: + +- A list of the authors of the software and their affiliations, using the correct format (see the example below). +- A summary describing the high-level functionality and purpose of the software for a diverse, *non-specialist audience*. +- A *Statement of need* section that clearly illustrates the research purpose of the software and places it in the context of related work. +- A list of key references, including to other software addressing related needs. Note that the references should include full names of venues, e.g., journals and conferences, not abbreviations only understood in the context of a specific discipline. +- Mention (if applicable) a representative set of past or ongoing research projects using the software and recent scholarly publications enabled by it. +- Acknowledgement of any financial support. + +As this short list shows, JOSS papers are only expected to contain a limited set of metadata (see example below), a Statement of need, Summary, Acknowledgements, and References sections. You can look at an [example accepted paper](example_paper). Given this format, a "full length" paper is not permitted, and software documentation such as API (Application Programming Interface) functionality should not be in the paper and instead should be outlined in the software documentation. + +```{important} +Your paper will be reviewed by two or more reviewers in a public GitHub issue. Take a look at the [review checklist](review_checklist) and [review criteria](review_criteria) to better understand how your submission will be reviewed. +``` + +## Article metadata + +(author-names)= +### Names + +Providing an author name is straight-forward: just set the `name` attribute. However, sometimes more control over the name is required. + +#### Name parts + +There are many ways to describe the parts of names; we support the following: + +- given names, +- surname, +- dropping particle, +- non-dropping particle, +- and suffix. + +We use a heuristic to parse names into these components. This parsing may produce the wrong result, in which case it is necessary to provide the relevant parts explicitly. + +The respective field names are + +- `given-names` (aliases: `given`, `first`, `firstname`) +- `surname` (aliases: `family`) +- `suffix` + +The full display name will be constructed from these parts, unless the `name` attribute is given as well. + +#### Particles + +It's usually enough to place particles like "van", "von", "della", etc. at the end of the given name or at the beginning of the surname, depending on the details of how the name is used. + +- `dropping-particle` +- `non-dropping-particle` + +#### Literal names + +The automatic construction of the full name from parts is geared towards common Western names. It may therefore be necessary sometimes to provide the display name explicitly. This is possible by setting the `literal` field, e.g., `literal: Tachibana Taki`. This feature should only be used as a last resort. + +#### Example + +```yaml +authors: + - name: John Doe + affiliation: '1' + + - given-names: Ludwig + dropping-particle: van + surname: Beethoven + affiliation: '3' + + # not recommended, but common aliases can be used for name parts. + - given: Louis + non-dropping-particle: de + family: Broglie + affiliation: '4' +``` + +The name parts can also be collected under the author's `name`: + +``` yaml +authors: + - name: + given-names: Kari + surname: Nordmann +``` + + + + + + + +## Internal references + +The goal of Open Journals is to provide authors with a seamless and pleasant writing experience. Since Markdown has no default mechanism to handle document internal references, known as “cross-references”, Open Journals supports a limited set of LaTex commands. In brief, elements that were marked with `\label` and can be referenced with `\ref` and `\autoref`. + +[Open Journals]: https://theoj.org + + ![View of coastal dunes in a nature reserve on Sylt, an island in + the North Sea. Sylt (Danish: *Slid*) is Germany's northernmost + island.](sylt.jpg){#sylt width="100%"} + +### Tables and figures + +Tables and figures can be referenced if they are given a *label* in the caption. In pure Markdown, this can be done by adding an empty span `[]{label="floatlabel"}` to the caption. LaTeX syntax is supported as well: `\label{floatlabel}`. + +Link to a float element, i.e., a table or figure, with `\ref{identifier}` or `\autoref{identifier}`, where `identifier` must be defined in the float's caption. The former command results in just the float's number, while the latter inserts the type and number of the referenced float. E.g., in this document `\autoref{proglangs}` yields "\autoref{proglangs}", while `\ref{proglangs}` gives "\ref{proglangs}". + +: Comparison of programming languages used in the publishing tool. []{label="proglangs"} + + | Language | Typing | Garbage Collected | Evaluation | Created | + |----------|:---------------:|:-----------------:|------------|---------| + | Haskell | static, strong | yes | non-strict | 1990 | + | Lua | dynamic, strong | yes | strict | 1993 | + | C | static, weak | no | strict | 1972 | + +### Equations + +Cross-references to equations work similarly to those for floating elements. The difference is that, since captions are not supported for equations, the label must be included in the equation: + + $$a^n + b^n = c^n \label{fermat}$$ + +Referencing, however, is identical, with `\autoref{eq:fermat}` resulting in "\autoref{eq:fermat}". + +$$a^n + b^n = c^n \label{eq:fermat}$$ + +Authors who do not wish to include the label directly in the formula can use a Markdown span to add the label: + + [$$a^n + b^n = c^n$$]{label="eq:fermat"} + +## Markdown +Markdown is a lightweight markup language used frequently in software development and online environments. Based on email conventions, it was developed in 2004 by John Gruber and Aaron Swartz. + +### Inline markup + +The markup in Markdown should be semantic, not presentations. The table below has some basic examples. + + +| Markup | Markdown example | Rendered output | +|:--------------------|:------------------------|:----------------------| +| emphasis | `*this*` | *this* | +| strong emphasis | `**that**` | **that** | +| strikeout | `~~not this~~` | ~~not this~~ | +| subscript | `H~2~O` | H{sub}`2`O | +| superscript | `Ca^2+^` | Ca{sup}`2+` | +| underline | `[underline]{.ul}` | [underline]{.ul} | +| small caps | `[Small Caps]{.sc}` | [Small Caps]{.sc} | +| inline code | `` `return 23` `` | `return 23` | + +### Links + +Link syntax is `[link description](targetURL)`. E.g., this link to the [Journal of Open Source Software](https://joss.theoj.org/) is written as \ +`[Journal of Open Source Software](https://joss.theoj.org/)`. + +Open Journal publications are not limited by the constraints of print publications. We encourage authors to use hyperlinks for websites and other external resources. However, the standard scientific practice of citing the relevant publications should be followed regardless. + +### Grid Tables + +Grid tables are made up of special characters which form the rows and columns, and also change table and style variables. + +Complex information can be conveyed by using the following features not found in other table styles: + +* spanning columns +* adding footers +* using intra-cellular body elements +* creating multi-row headers + +Grid table syntax uses the characters "-", "=", "|", and "+" to represent the table outline: + +* Hyphens (-) separate horizontal rows. +* Equals signs (=) produce a header when used to create the row under the header text. +* Equals signs (=) create a footer when used to enclose the last row of the table. +* Vertical bars (|) separate columns and also adjusts the depth of a row. +* Plus signs (+) indicates a juncture between horizontal and parallel lines. + +Note: Inserting a colon (:) at the boundaries of the separator line after the header will change text alignment. If there is no header, insert colons into the top line. + +Sample grid table: + + +-------------------+------------+----------+----------+ + | Header 1 | Header 2 | Header 3 | Header 4 | + | | | | | + +:=================:+:==========:+:========:+:========:+ + | row 1, column 1 | column 2 | column 3 | column 4 | + +-------------------+------------+----------+----------+ + | row 2 | cells span columns | + +-------------------+------------+---------------------+ + | row 3 | cells | - body | + +-------------------+ span rows | - elements | + | row 4 | | - here | + +===================+============+=====================+ + | Footer | + +===================+============+=====================+ + +### Figures and Images + +To create a figure, a captioned image must appear by itself in a paragraph. The Markdown syntax for a figure is a link, preceded by an exclamation point (!) and a description. +Example: +`![This description will be the figure caption](path/to/image.png)` + +In order to create a figure rather than an image, there must be a description included and the figure syntax must be the only element in the paragraph, i.e., it must be surrounded by blank lines. + +Images that are larger than the text area are scaled to fit the page. You can give images an explicit height and/or width, e.g. when adding an image as part of a paragraph. The Markdown `![Nyan cat](nyan-cat.png){height="9pt"}` includes the image saved as `nyan-cat.png` while scaling it to a height of 9 pt. + +### Citations + +Bibliographic data should be collected in a file `paper.bib`; it should be formatted in the BibLaTeX format, although plain BibTeX is acceptable as well. All major citation managers offer to export these formats. + +Cite a bibliography entry by referencing its identifier: `[@upper1974]` +will create the reference "(Upper 1974)". Omit the brackets when +referring to the author as part of a sentence: "For a case study on +writers block, see Upper (1974)." Please refer to the [pandoc +manual](https://pandoc.org/MANUAL#extension-citations) for additional +features, including page locators, prefixes, suffixes, and suppression +of author names in citations. + +The full citation will display as + +> Upper, D. 1974. "The Unsuccessful Self-Treatment of a Case of \"Writer's +> Block\"." *Journal of Applied Behavior Analysis* 7 (3): 497. +> . + +### Mathematical Formulæ + +Mark equations and other math content with dollar signs ($). Use a single dollar sign ($) for math that will appear directly within the text. Use two dollar signs ($$) when the formula is to be presented centered and on a separate line, in "display" style. The formula itself must be given using TeX syntax. + +To give some examples: When discussing a variable *x* or a short formula like + +```{math} +\sin \frac{\pi}{2} +``` + +we would write $x$ and + + $\sin \frac{\pi}{2}$ + +respectively. However, for more complex formulæ, display style is more appropriate. Writing + + $$\int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}$$ + +will give us + +$$\int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}$$ + +### Footnotes + +Syntax for footnotes centers around the "caret" character `^`. The symbol is also used as a delimiter for superscript text and thereby mirrors the superscript numbers used to mark a footnote in the final text. + +``` markdown +Articles are published under a Creative Commons license[^1]. +Software should use an OSI-approved license. + +[^1]: An open license that allows reuse. +``` + +The above example results in the following output: + +> ```{eval_rst} +> +> Articles are published under a Creative Commons license [#f1]_. Software should use an OSI-approved license. +> +> .. rubric:: Footnotes +> +> .. [#f1] An open license that allows reuse. +> +> ``` + +Note: numbers do not have to be sequential, they will be reordered automatically in the publishing step. In fact, the identifier of a note can be any sequence of characters, like `[^marker]`, but may not contain whitespace characters. + + +### Blocks + +The larger components of a document are called "blocks". + +#### Headings + +Headings are added with `#` followed by a space, where each additional `#` demotes the heading to a level lower in the hierarchy: + +```markdown +# Section + +## Subsection + +### Subsubsection +``` + +Please start headings on the first level. The maximum supported level is 5, but paper authors are encouraged to limit themselves to headings of the first two or three levels. + +##### Deeper nesting + +Fourth- and fifth-level subsections – like this one and the following heading – are supported by the system; however, their use is discouraged. Use lists instead of fourth- and fifth-level headings. + + +### Lists + +Bullet lists and numbered lists, a.k.a. enumerations, offer an additional method to present sequential and hierarchical information. + +``` markdown +- apples +- citrus fruits + - lemons + - oranges +``` + +- apples +- citrus fruits + - lemons + - oranges + +Enumerations start with the number of the first item. Using the the first two [laws of thermodynamics](https://en.wikipedia.org/wiki/Laws_of_thermodynamics) as example, + +``` markdown +0. If two systems are each in thermal equilibrium with a third, they are + also in thermal equilibrium with each other. +1. In a process without transfer of matter, the change in internal + energy, $\Delta U$, of a thermodynamic system is equal to the energy + gained as heat, $Q$, less the thermodynamic work, $W$, done by the + system on its surroundings. $$\Delta U = Q - W$$ +``` + +Rendered: + +0. If two systems are each in thermal equilibrium with a third, they are also in thermal equilibrium with each other. +1. In a process without transfer of matter, the change in internal energy, $\Delta U$, of a thermodynamic system is equal to the energy gained as heat, $Q$, less the thermodynamic work, $W$, done by the system on its surroundings. $$\Delta U = Q - W$$ + + +## Checking that your paper compiles + +JOSS uses Pandoc to compile papers from their Markdown form into a PDF. There are a few different ways you can test that your paper is going to compile properly for JOSS: + +### GitHub Action + +If you're using GitHub for your repository, you can use the [Open Journals GitHub Action](https://github.com/marketplace/actions/open-journals-pdf-generator) to automatically compile your paper each time you update your repository. + +The PDF is available via the Actions tab in your project and click on the latest workflow run. The zip archive file (including the `paper.pdf`) is listed in the run's Artifacts section. + +### Docker + +If you have Docker installed on your local machine, you can use the same Docker Image to compile a draft of your paper locally. In the example below, the `paper.md` file is in the `paper` directory. Upon successful execution of the command, the `paper.pdf` file will be created in the same location as the `paper.md` file: + +```text +docker run --rm \ + --volume $PWD/paper:/data \ + --user $(id -u):$(id -g) \ + --env JOURNAL=joss \ + openjournals/inara +``` + +### Locally + +The materials for the `inara` container image above are themselves open source and available in [its own repository](https://github.com/openjournals/inara). You can clone that repository and run the `inara` script locally with `make` after installing the necessary dependencies, which can be inferred from the [`Dockerfile`](https://github.com/openjournals/inara/blob/main/Dockerfile). + +## Behind the scenes + +Readers may wonder about the reasons behind some of the choices made for paper writing. Most often, the decisions were driven by radical pragmatism. For example, Markdown is not only nearly ubiquitous in the realms of software, but it can also be converted into many different output formats. The archiving standard for scientific articles is JATS, and the most popular publishing format is PDF. Open Journals has built its pipeline based on [pandoc](https://pandoc.org), a universal document converter that can produce both of these publishing formats as well as many more. + +A common method for PDF generation is to go via LaTeX. However, support for tagging -- a requirement for accessible PDFs -- is not readily available for LaTeX. The current method used ConTeXt, to produce tagged PDF/A-3. diff --git a/docs/requirements.txt b/docs/requirements.txt index c935b13a..4a067476 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ docutils +linkify-it-py sphinx_rtd_theme myst-parser diff --git a/docs/review_criteria.md b/docs/review_criteria.md index a8c3ab32..ac1b7fb7 100644 --- a/docs/review_criteria.md +++ b/docs/review_criteria.md @@ -2,7 +2,7 @@ ## The JOSS paper -As outlined in the [submission guidelines provided to authors](submitting.md#what-should-my-paper-contain), the JOSS paper (the compiled PDF associated with this submission) should only include: +As outlined in the [submission guidelines provided to authors](paper.md#what-should-my-paper-contain), the JOSS paper (the compiled PDF associated with this submission) should only include: - A list of the authors of the software and their affiliations. - A summary describing the high-level functionality and purpose of the software for a diverse, non-specialist audience. diff --git a/docs/sample_messages.md b/docs/sample_messages.md new file mode 100644 index 00000000..9a0f9ddf --- /dev/null +++ b/docs/sample_messages.md @@ -0,0 +1,96 @@ +# Sample messages for authors and reviewers + +## Sample email to potential reviewers + +``` +Dear Dr. Jekyll, + +I found you following links from the page of The Super Project and/or on Twitter. This +message is to ask if you can help us out with a submission to JOSS (The Journal of Open +Source Software, https://joss.theoj.org), where I’m an editor. + +JOSS publishes articles about open source research software. The submission I'd like you +to review is titled: "great software name here" + +and the submission repository is at: https://github.com/< … > + +JOSS is a free, open-source, community driven and developer-friendly online journal +(no publisher is seeking to raise revenue from the volunteer labor of researchers!). + +The review process at JOSS is unique: it takes place in a GitHub issue, is open, +and author-reviewer-editor conversations are encouraged. + +JOSS reviews involve downloading and installing the software, and inspecting the repository +and submitted paper for key elements. See https://joss.readthedocs.io/en/latest/review_criteria.html + +Editors and reviewers post comments on the Review issue, and authors respond to the comments +and improve their submission until acceptance (or withdrawal, if they feel unable to +satisfy the review). + +Would you be able to review this submission for JOSS? If not, can you recommend +someone from your team to help out? + +Kind regards, + +JOSS Editor. +``` + +## Query scope of submission + +``` +:wave: thanks for your submission to JOSS. From a quick inspection of this submission it's not entirely obvious that it meets our [submission criteria](https://joss.readthedocs.io/en/latest/submitting.html#submission-requirements). In particular, this item: + +> - Your software should have an obvious research application + +Could you confirm here that there _is_ a research application for this software (and explain what that application is)? The section [_'what should my paper contain'_](https://joss.readthedocs.io/en/latest/submitting.html#what-should-my-paper-contain) has some guidance for the sort of content we're looking to be present in the `paper.md`. + +Many thanks! +``` + +## GitHub invite to potential reviewers + +``` +:wave: @reviewer1 & @reviewer2, would any of you be willing to review this submission for JOSS? We carry out our checklist-driven reviews here in GitHub issues and follow these guidelines: https://joss.readthedocs.io/en/latest/review_criteria.html +``` + +## Message to reviewers at the start of a review + +``` +👋🏼 @authorname @reviewer1 @reviewer2 this is the review thread for the paper. All of our communications will happen here from now on. + +As a reviewer, the first step is to create a checklist for your review by entering + +```@editorialbot generate my checklist``` + +as the top of a new comment in this thread. + +These checklists contain the JOSS requirements. As you go over the submission, please check any items that you feel have been satisfied. The first comment in this thread also contains links to the JOSS reviewer guidelines. + +The JOSS review is different from most other journals. Our goal is to work with the authors to help them meet our criteria instead of merely passing judgment on the submission. As such, the reviewers are encouraged to submit issues and pull requests on the software repository. When doing so, please mention `openjournals/joss-reviews#REVIEW_NUMBER` so that a link is created to this thread (and I can keep an eye on what is happening). Please also feel free to comment and ask questions on this thread. In my experience, it is better to post comments/questions/suggestions as you come across them instead of waiting until you've reviewed the entire package. + +We aim for reviews to be completed within about 2-4 weeks. Please let me know if any of you require some more time. We can also use EditorialBot (our bot) to set automatic reminders if you know you'll be away for a known period of time. + +Please feel free to ping me (@editorname) if you have any questions/concerns. +``` + +## Message to authors at the end of a review + +``` +At this point could you: +- Make a tagged release of your software, and list the version tag of the archived version here. +- Archive the reviewed software in Zenodo or a similar service (e.g., figshare, an institutional repository) +- Check the archival deposit (e.g., in Zenodo) has the correct metadata. This includes the title (should match the paper title) and author list (make sure the list is correct and people who only made a small fix are not on it). You may also add the authors' ORCID. +- Please list the DOI of the archived version here. + +I can then move forward with recommending acceptance of the submission. +``` + +## Rejection due to out of scope/failing substantial scholarly effort test + +(Note that rejections are handled by EiCs and not individual editors). + +``` +@authorname - thanks for your submission to JOSS. Unfortunately, after review by the JOSS editorial team we've determined that this submission doesn't meet our [substantial scholarly effort](https://joss.readthedocs.io/en/latest/submitting.html#substantial-scholarly-effort) criterion. + +One possible alternative to JOSS is to follow [GitHub's guide](https://guides.github.com/activities/citable-code/) on how to create a permanent archive and DOI for your software. This DOI can then be used by others to cite your work. +``` diff --git a/docs/submitting.md b/docs/submitting.md index 41c3242a..ee79e576 100644 --- a/docs/submitting.md +++ b/docs/submitting.md @@ -53,11 +53,7 @@ Authors wishing to publish software deemed out of scope for JOSS have a few opti While we are happy to review submissions in standalone repositories, we also review submissions that are significant contributions made to existing packages. It is often better to have an integrated library or package of methods than a large number of single-method packages. -## Conflict of Interest policy for authors - -An author conflict of interest (COI) arises when an author has financial, personal, or other interests that may influence their research or the interpretation of its results. In order to maintain the integrity of the work published in JOSS, we require that authors disclose any potential conflicts of interest at submission time. - -### Policy +## Policies **Disclosure:** All authors must disclose any potential conflicts of interest related to the research in their manuscript, including financial, personal, or professional relationships that may affect their objectivity. This includes any financial relationships, such as employment, consultancies, honoraria, stock ownership, or other financial interests that may be relevant to the research. @@ -69,608 +65,46 @@ An author conflict of interest (COI) arises when an author has financial, person **Review and Update:** This COI policy will be reviewed and updated regularly to ensure it remains relevant and effective. -## Typical paper submission flow - -Before you submit, you should: - -- Make your software available in an open repository (GitHub, Bitbucket, etc.) and include an [OSI approved open source license](https://opensource.org/licenses). -- Make sure that the software complies with the [JOSS review criteria](review_criteria). In particular, your software should be full-featured, well-documented, and contain procedures (such as automated tests) for checking correctness. -- Write a short paper in Markdown format using `paper.md` as file name, including a title, summary, author names, affiliations, and key references. See our [example paper](#example-paper-and-bibliography) to follow the correct format. -- (Optional) create a metadata file describing your software and include it in your repository. We provide [a script](https://gist.github.com/arfon/478b2ed49e11f984d6fb) that automates the generation of this metadata. - -## What should my paper contain? - -```{important} -Begin your paper with a summary of the high-level functionality of your software for a non-specialist reader. Avoid jargon in this section. -``` - -JOSS welcomes submissions from broadly diverse research areas. For this reason, we require that authors include in the paper some sentences that explain the software functionality and domain of use to a non-specialist reader. We also require that authors explain the research applications of the software. The paper should be between 250-1000 words. Authors submitting papers significantly longer than 1000 words may be asked to reduce the length of their paper. - -Your paper should include: - -- A list of the authors of the software and their affiliations, using the correct format (see the example below). -- A summary describing the high-level functionality and purpose of the software for a diverse, *non-specialist audience*. -- A *Statement of need* section that clearly illustrates the research purpose of the software and places it in the context of related work. -- A list of key references, including to other software addressing related needs. Note that the references should include full names of venues, e.g., journals and conferences, not abbreviations only understood in the context of a specific discipline. -- Mention (if applicable) a representative set of past or ongoing research projects using the software and recent scholarly publications enabled by it. -- Acknowledgement of any financial support. - -As this short list shows, JOSS papers are only expected to contain a limited set of metadata (see example below), a Statement of need, Summary, Acknowledgements, and References sections. You can look at an [example accepted paper](#example-paper-and-bibliography). Given this format, a "full length" paper is not permitted, and software documentation such as API (Application Programming Interface) functionality should not be in the paper and instead should be outlined in the software documentation. - -```{important} -Your paper will be reviewed by two or more reviewers in a public GitHub issue. Take a look at the [review checklist](review_checklist) and [review criteria](review_criteria) to better understand how your submission will be reviewed. -``` - -## How should my paper be formatted? - -Submitted articles must use Markdown and must provide a metadata section at the beginning of the article. Format metadata using YAML, a human-friendly data serialization language (The Official YAML Web Site, 2022). The information provided is included in the title and sidebar of the generated PDF. - -### Article metadata - -(author-names)= -#### Names - -Providing an author name is straight-forward: just set the `name` attribute. However, sometimes more control over the name is required. - -##### Name parts - -There are many ways to describe the parts of names; we support the following: - -- given names, -- surname, -- dropping particle, -- non-dropping particle, -- and suffix. - -We use a heuristic to parse names into these components. This parsing may produce the wrong result, in which case it is necessary to provide the relevant parts explicitly. - -The respective field names are - -- `given-names` (aliases: `given`, `first`, `firstname`) -- `surname` (aliases: `family`) -- `suffix` - -The full display name will be constructed from these parts, unless the `name` attribute is given as well. - -##### Particles - -It's usually enough to place particles like "van", "von", "della", etc. at the end of the given name or at the beginning of the surname, depending on the details of how the name is used. - -- `dropping-particle` -- `non-dropping-particle` - -##### Literal names - -The automatic construction of the full name from parts is geared towards common Western names. It may therefore be necessary sometimes to provide the display name explicitly. This is possible by setting the `literal` field, e.g., `literal: Tachibana Taki`. This feature should only be used as a last resort. - -##### Example - -```yaml -authors: - - name: John Doe - affiliation: '1' - - - given-names: Ludwig - dropping-particle: van - surname: Beethoven - affiliation: '3' - - # not recommended, but common aliases can be used for name parts. - - given: Louis - non-dropping-particle: de - family: Broglie - affiliation: '4' -``` - -The name parts can also be collected under the author's `name`: - -``` yaml -authors: - - name: - given-names: Kari - surname: Nordmann -``` - - - - - - - -### Internal references - -The goal of Open Journals is to provide authors with a seamless and pleasant writing experience. Since Markdown has no default mechanism to handle document internal references, known as “cross-references”, Open Journals supports a limited set of LaTex commands. In brief, elements that were marked with `\label` and can be referenced with `\ref` and `\autoref`. - -[Open Journals]: https://theoj.org - - ![View of coastal dunes in a nature reserve on Sylt, an island in - the North Sea. Sylt (Danish: *Slid*) is Germany's northernmost - island.](sylt.jpg){#sylt width="100%"} - -#### Tables and figures - -Tables and figures can be referenced if they are given a *label* in the caption. In pure Markdown, this can be done by adding an empty span `[]{label="floatlabel"}` to the caption. LaTeX syntax is supported as well: `\label{floatlabel}`. - -Link to a float element, i.e., a table or figure, with `\ref{identifier}` or `\autoref{identifier}`, where `identifier` must be defined in the float's caption. The former command results in just the float's number, while the latter inserts the type and number of the referenced float. E.g., in this document `\autoref{proglangs}` yields "\autoref{proglangs}", while `\ref{proglangs}` gives "\ref{proglangs}". - -: Comparison of programming languages used in the publishing tool. []{label="proglangs"} - - | Language | Typing | Garbage Collected | Evaluation | Created | - |----------|:---------------:|:-----------------:|------------|---------| - | Haskell | static, strong | yes | non-strict | 1990 | - | Lua | dynamic, strong | yes | strict | 1993 | - | C | static, weak | no | strict | 1972 | - -#### Equations - -Cross-references to equations work similarly to those for floating elements. The difference is that, since captions are not supported for equations, the label must be included in the equation: - - $$a^n + b^n = c^n \label{fermat}$$ - -Referencing, however, is identical, with `\autoref{eq:fermat}` resulting in "\autoref{eq:fermat}". - -$$a^n + b^n = c^n \label{eq:fermat}$$ - -Authors who do not wish to include the label directly in the formula can use a Markdown span to add the label: - - [$$a^n + b^n = c^n$$]{label="eq:fermat"} - -### Behind the scenes - -Readers may wonder about the reasons behind some of the choices made for paper writing. Most often, the decisions were driven by radical pragmatism. For example, Markdown is not only nearly ubiquitous in the realms of software, but it can also be converted into many different output formats. The archiving standard for scientific articles is JATS, and the most popular publishing format is PDF. Open Journals has built its pipeline based on [pandoc](https://pandoc.org), a universal document converter that can produce both of these publishing formats as well as many more. - -A common method for PDF generation is to go via LaTeX. However, support for tagging -- a requirement for accessible PDFs -- is not readily available for LaTeX. The current method used ConTeXt, to produce tagged PDF/A-3. - -### Markdown -Markdown is a lightweight markup language used frequently in software development and online environments. Based on email conventions, it was developed in 2004 by John Gruber and Aaron Swartz. - -#### Inline markup - -The markup in Markdown should be semantic, not presentations. The table below has some basic examples. - - +---------------------+-------------------------+-----------------------+ - | Markup | Markdown example | Rendered output | - +:====================+:=======================:+:=====================:+ - | emphasis | `*this*` | *this* | - +---------------------+-------------------------+-----------------------+ - | strong emphasis | `**that**` | **that** | - +---------------------+-------------------------+-----------------------+ - | strikeout | `~~not this~~` | ~~not this~~ | - +---------------------+-------------------------+-----------------------+ - | subscript | `H~2~O` | H~2~O | - +---------------------+-------------------------+-----------------------+ - | superscript | `Ca^2+^` | Ca^2+^ | - +---------------------+-------------------------+-----------------------+ - | underline | `[underline]{.ul}` | [underline]{.ul} | - +---------------------+-------------------------+-----------------------+ - | small caps | `[Small Caps]{.sc}` | [Small Caps]{.sc} | - +---------------------+-------------------------+-----------------------+ - | inline code | `` `return 23` `` | `return 23` | - +---------------------+-------------------------+-----------------------+ - -#### Links - -Link syntax is `[link description](targetURL)`. E.g., this link to the [Journal of Open Source Software](https://joss.theoj.org/) is written as \ -`[Journal of Open Source Software](https://joss.theoj.org/)`. - -Open Journal publications are not limited by the constraints of print publications. We encourage authors to use hyperlinks for websites and other external resources. However, the standard scientific practice of citing the relevant publications should be followed regardless. +### Conflict of Interest policy for authors -#### Grid Tables - -Grid tables are made up of special characters which form the rows and columns, and also change table and style variables. - -Complex information can be conveyed by using the following features not found in other table styles: - -* spanning columns -* adding footers -* using intra-cellular body elements -* creating multi-row headers - -Grid table syntax uses the characters "-", "=", "|", and "+" to represent the table outline: - -* Hyphens (-) separate horizontal rows. -* Equals signs (=) produce a header when used to create the row under the header text. -* Equals signs (=) create a footer when used to enclose the last row of the table. -* Vertical bars (|) separate columns and also adjusts the depth of a row. -* Plus signs (+) indicates a juncture between horizontal and parallel lines. - -Note: Inserting a colon (:) at the boundaries of the separator line after the header will change text alignment. If there is no header, insert colons into the top line. - -Sample grid table: - - +-------------------+------------+----------+----------+ - | Header 1 | Header 2 | Header 3 | Header 4 | - | | | | | - +:=================:+:==========:+:========:+:========:+ - | row 1, column 1 | column 2 | column 3 | column 4 | - +-------------------+------------+----------+----------+ - | row 2 | cells span columns | - +-------------------+------------+---------------------+ - | row 3 | cells | - body | - +-------------------+ span rows | - elements | - | row 4 | | - here | - +===================+============+=====================+ - | Footer | - +===================+============+=====================+ - -#### Figures and Images - -To create a figure, a captioned image must appear by itself in a paragraph. The Markdown syntax for a figure is a link, preceded by an exclamation point (!) and a description. -Example: -`![This description will be the figure caption](path/to/image.png)` - -In order to create a figure rather than an image, there must be a description included and the figure syntax must be the only element in the paragraph, i.e., it must be surrounded by blank lines. - -Images that are larger than the text area are scaled to fit the page. You can give images an explicit height and/or width, e.g. when adding an image as part of a paragraph. The Markdown `![Nyan cat](nyan-cat.png){height="9pt"}` includes the image saved as `nyan-cat.png` while scaling it to a height of 9 pt. - -#### Citations - -Bibliographic data should be collected in a file `paper.bib`; it should be formatted in the BibLaTeX format, although plain BibTeX is acceptable as well. All major citation managers offer to export these formats. - -Cite a bibliography entry by referencing its identifier: `[@upper1974]` -will create the reference "(Upper 1974)". Omit the brackets when -referring to the author as part of a sentence: "For a case study on -writers block, see Upper (1974)." Please refer to the [pandoc -manual](https://pandoc.org/MANUAL#extension-citations) for additional -features, including page locators, prefixes, suffixes, and suppression -of author names in citations. - -The full citation will display as - -> Upper, D. 1974. "The Unsuccessful Self-Treatment of a Case of \"Writer's -> Block\"." *Journal of Applied Behavior Analysis* 7 (3): 497. -> . - -#### Mathematical Formulæ - -Mark equations and other math content with dollar signs ($). Use a single dollar sign ($) for math that will appear directly within the text. Use two dollar signs ($$) when the formula is to be presented centered and on a separate line, in "display" style. The formula itself must be given using TeX syntax. - -To give some examples: When discussing a variable *x* or a short formula like - -```{math} -\sin \frac{\pi}{2} -``` - -we would write $x$ and - - $\sin \frac{\pi}{2}$ - -respectively. However, for more complex formulæ, display style is more appropriate. Writing - - $$\int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}$$ - -will give us - -$$\int_{-\infty}^{+\infty} e^{-x^2} \, dx = \sqrt{\pi}$$ - -#### Footnotes - -Syntax for footnotes centers around the "caret" character `^`. The symbol is also used as a delimiter for superscript text and thereby mirrors the superscript numbers used to mark a footnote in the final text. - -``` markdown -Articles are published under a Creative Commons license[^1]. -Software should use an OSI-approved license. - -[^1]: An open license that allows reuse. -``` - -The above example results in the following output: - -> ```{eval_rst} -> -> Articles are published under a Creative Commons license [#f1]_. Software should use an OSI-approved license. -> -> .. rubric:: Footnotes -> -> .. [#f1] An open license that allows reuse. -> -> ``` - -Note: numbers do not have to be sequential, they will be reordered automatically in the publishing step. In fact, the identifier of a note can be any sequence of characters, like `[^marker]`, but may not contain whitespace characters. - - -#### Blocks - -The larger components of a document are called "blocks". - -##### Headings - -Headings are added with `#` followed by a space, where each additional `#` demotes the heading to a level lower in the hierarchy: - -```markdown -# Section - -## Subsection - -### Subsubsection -``` - -Please start headings on the first level. The maximum supported level is 5, but paper authors are encouraged to limit themselves to headings of the first two or three levels. - -###### Deeper nesting - -Fourth- and fifth-level subsections – like this one and the following heading – are supported by the system; however, their use is discouraged. Use lists instead of fourth- and fifth-level headings. - - -#### Lists +An author conflict of interest (COI) arises when an author has financial, personal, or other interests that may influence their research or the interpretation of its results. In order to maintain the integrity of the work published in JOSS, we require that authors disclose any potential conflicts of interest at submission time. -Bullet lists and numbered lists, a.k.a. enumerations, offer an additional method to present sequential and hierarchical information. +### Preprint Policy -``` markdown -- apples -- citrus fruits - - lemons - - oranges -``` +Authors are welcome to submit their papers to a preprint server ([arXiv](https://arxiv.org/), [bioRxiv](https://www.biorxiv.org/), [SocArXiv](https://socopen.org/), [PsyArXiv](https://psyarxiv.com/) etc.) at any point before, during, or after the submission and review process. -- apples -- citrus fruits - - lemons - - oranges +Submission to a preprint server is _not_ considered a previous publication. -Enumerations start with the number of the first item. Using the the first two [laws of thermodynamics](https://en.wikipedia.org/wiki/Laws_of_thermodynamics) as example, +### Authorship -``` markdown -0. If two systems are each in thermal equilibrium with a third, they are - also in thermal equilibrium with each other. -1. In a process without transfer of matter, the change in internal - energy, $\Delta U$, of a thermodynamic system is equal to the energy - gained as heat, $Q$, less the thermodynamic work, $W$, done by the - system on its surroundings. $$\Delta U = Q - W$$ -``` +Purely financial (such as being named on an award) and organizational (such as general supervision of a research group) contributions are not considered sufficient for co-authorship of JOSS submissions, but active project direction and other forms of non-code contributions are. The authors themselves assume responsibility for deciding who should be credited with co-authorship, and co-authors must always agree to be listed. In addition, co-authors agree to be accountable for all aspects of the work, and to notify JOSS if any retraction or correction of mistakes are needed after publication. -Rendered: +### Submissions using proprietary languages/development environments -0. If two systems are each in thermal equilibrium with a third, they are also in thermal equilibrium with each other. -1. In a process without transfer of matter, the change in internal energy, $\Delta U$, of a thermodynamic system is equal to the energy gained as heat, $Q$, less the thermodynamic work, $W$, done by the system on its surroundings. $$\Delta U = Q - W$$ +We strongly prefer software that doesn't rely upon proprietary (paid for) development environments/programming languages. However, provided _your submission meets our requirements_ (including having a valid open source license) then we will consider your submission for review. Should your submission be accepted for review, we may ask you, the submitting author, to help us find reviewers who already have the required development environment installed. -## Example paper and bibliography +## Submission Process -This example `paper.md` is adapted from _Gala: A Python package for galactic dynamics_ by Adrian M. Price-Whelan [http://doi.org/10.21105/joss.00388](http://doi.org/10.21105/joss.00388). +Before you submit, you should: -For a complete description of available options to describe author names [see here](author-names). +- Make your software available in an open repository (GitHub, Bitbucket, etc.) and include an [OSI approved open source license](https://opensource.org/licenses). +- Make sure that the software complies with the [JOSS review criteria](review_criteria). In particular, your software should be full-featured, well-documented, and contain procedures (such as automated tests) for checking correctness. +- Write a short paper in Markdown format using `paper.md` as file name, including a title, summary, author names, affiliations, and key references. See our [example paper](example_paper) to follow the correct format. +- (Optional) create a metadata file describing your software and include it in your repository. We provide [a script](https://gist.github.com/arfon/478b2ed49e11f984d6fb) that automates the generation of this metadata. -```markdown ---- -title: 'Gala: A Python package for galactic dynamics' -tags: - - Python - - astronomy - - dynamics - - galactic dynamics - - milky way -authors: - - name: Adrian M. Price-Whelan - orcid: 0000-0000-0000-0000 - equal-contrib: true - affiliation: "1, 2" # (Multiple affiliations must be quoted) - - name: Author Without ORCID - equal-contrib: true # (This is how you can denote equal contributions between multiple authors) - affiliation: 2 - - name: Author with no affiliation - corresponding: true # (This is how to denote the corresponding author) - affiliation: 3 - - given-names: Ludwig - dropping-particle: van - surname: Beethoven - affiliation: 3 -affiliations: - - name: Lyman Spitzer, Jr. Fellow, Princeton University, USA - index: 1 - - name: Institution Name, Country - index: 2 - - name: Independent Researcher, Country - index: 3 -date: 13 August 2017 -bibliography: paper.bib - -# Optional fields if submitting to a AAS journal too, see this blog post: -# https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing -aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it. -aas-journal: Astrophysical Journal <- The name of the AAS journal. ---- - -# Summary - -The forces on stars, galaxies, and dark matter under external gravitational -fields lead to the dynamical evolution of structures in the universe. The orbits -of these bodies are therefore key to understanding the formation, history, and -future state of galaxies. The field of "galactic dynamics," which aims to model -the gravitating components of galaxies to study their structure and evolution, -is now well-established, commonly taught, and frequently used in astronomy. -Aside from toy problems and demonstrations, the majority of problems require -efficient numerical tools, many of which require the same base code (e.g., for -performing numerical orbit integration). - -# Statement of need - -`Gala` is an Astropy-affiliated Python package for galactic dynamics. Python -enables wrapping low-level languages (e.g., C) for speed without losing -flexibility or ease-of-use in the user-interface. The API for `Gala` was -designed to provide a class-based and user-friendly interface to fast (C or -Cython-optimized) implementations of common operations such as gravitational -potential and force evaluation, orbit integration, dynamical transformations, -and chaos indicators for nonlinear dynamics. `Gala` also relies heavily on and -interfaces well with the implementations of physical units and astronomical -coordinate systems in the `Astropy` package [@astropy] (`astropy.units` and -`astropy.coordinates`). - -`Gala` was designed to be used by both astronomical researchers and by -students in courses on gravitational dynamics or astronomy. It has already been -used in a number of scientific publications [@Pearson:2017] and has also been -used in graduate courses on Galactic dynamics to, e.g., provide interactive -visualizations of textbook material [@Binney:2008]. The combination of speed, -design, and support for Astropy functionality in `Gala` will enable exciting -scientific explorations of forthcoming data releases from the *Gaia* mission -[@gaia] by students and experts alike. - -# Mathematics - -Single dollars ($) are required for inline mathematics e.g. $f(x) = e^{\pi/x}$ - -Double dollars make self-standing equations: - -$$\Theta(x) = \left\{\begin{array}{l} -0\textrm{ if } x < 0\cr -1\textrm{ else} -\end{array}\right.$$ - -You can also use plain \LaTeX for equations -\begin{equation}\label{eq:fourier} -\hat f(\omega) = \int_{-\infty}^{\infty} f(x) e^{i\omega x} dx -\end{equation} -and refer to \autoref{eq:fourier} from text. - -# Citations - -Citations to entries in paper.bib should be in -[rMarkdown](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html) -format. - -If you want to cite a software repository URL (e.g. something on GitHub without a preferred -citation) then you can do it with the example BibTeX entry below for @fidgit. - -For a quick reference, the following citation commands can be used: -- `@author:2001` -> "Author et al. (2001)" -- `[@author:2001]` -> "(Author et al., 2001)" -- `[@author1:2001; @author2:2001]` -> "(Author1 et al., 2001; Author2 et al., 2002)" - -# Figures - -Figures can be included like this: -![Caption for example figure.\label{fig:example}](figure.png) -and referenced from text using \autoref{fig:example}. - -Figure sizes can be customized by adding an optional second parameter: -![Caption for example figure.](figure.png){ width=20% } - -# Acknowledgements - -We acknowledge contributions from Brigitta Sipocz, Syrtis Major, and Semyeong -Oh, and support from Kathryn Johnston during the genesis of this project. - -# References - -``` - -Example `paper.bib` file: - -``` -@article{Pearson:2017, - url = {http://adsabs.harvard.edu/abs/2017arXiv170304627P}, - Archiveprefix = {arXiv}, - Author = {{Pearson}, S. and {Price-Whelan}, A.~M. and {Johnston}, K.~V.}, - Eprint = {1703.04627}, - Journal = {ArXiv e-prints}, - Keywords = {Astrophysics - Astrophysics of Galaxies}, - Month = mar, - Title = {{Gaps in Globular Cluster Streams: Pal 5 and the Galactic Bar}}, - Year = 2017 -} - -@book{Binney:2008, - url = {http://adsabs.harvard.edu/abs/2008gady.book.....B}, - Author = {{Binney}, J. and {Tremaine}, S.}, - Booktitle = {Galactic Dynamics: Second Edition, by James Binney and Scott Tremaine.~ISBN 978-0-691-13026-2 (HB).~Published by Princeton University Press, Princeton, NJ USA, 2008.}, - Publisher = {Princeton University Press}, - Title = {{Galactic Dynamics: Second Edition}}, - Year = 2008 -} - -@article{gaia, - author = {{Gaia Collaboration}}, - title = "{The Gaia mission}", - journal = {Astronomy and Astrophysics}, - archivePrefix = "arXiv", - eprint = {1609.04153}, - primaryClass = "astro-ph.IM", - keywords = {space vehicles: instruments, Galaxy: structure, astrometry, parallaxes, proper motions, telescopes}, - year = 2016, - month = nov, - volume = 595, - doi = {10.1051/0004-6361/201629272}, - url = {http://adsabs.harvard.edu/abs/2016A%26A...595A...1G}, -} - -@article{astropy, - author = {{Astropy Collaboration}}, - title = "{Astropy: A community Python package for astronomy}", - journal = {Astronomy and Astrophysics}, - archivePrefix = "arXiv", - eprint = {1307.6212}, - primaryClass = "astro-ph.IM", - keywords = {methods: data analysis, methods: miscellaneous, virtual observatory tools}, - year = 2013, - month = oct, - volume = 558, - doi = {10.1051/0004-6361/201322068}, - url = {http://adsabs.harvard.edu/abs/2013A%26A...558A..33A} -} - -@misc{fidgit, - author = {A. M. Smith and K. Thaney and M. Hahnel}, - title = {Fidgit: An ungodly union of GitHub and Figshare}, - year = {2020}, - publisher = {GitHub}, - journal = {GitHub repository}, - url = {https://github.com/arfon/fidgit} -} -``` - -Note that the paper begins by a metadata section (the enclosing --- lines are mandatory) and ends with a References heading, and the references are built automatically from the content in the `.bib` file. You should enter in-text citations in the paper body following correct [Markdown citation syntax](https://pandoc.org/MANUAL.html#extension-citations). Also note that the references include full names of venues, e.g., journals and conferences, not abbreviations only understood in the context of a specific discipline. - -## Checking that your paper compiles - -JOSS uses Pandoc to compile papers from their Markdown form into a PDF. There are a few different ways you can test that your paper is going to compile properly for JOSS: - -### GitHub Action - -If you're using GitHub for your repository, you can use the [Open Journals GitHub Action](https://github.com/marketplace/actions/open-journals-pdf-generator) to automatically compile your paper each time you update your repository. - -The PDF is available via the Actions tab in your project and click on the latest workflow run. The zip archive file (including the `paper.pdf`) is listed in the run's Artifacts section. - -### Docker - -If you have Docker installed on your local machine, you can use the same Docker Image to compile a draft of your paper locally. In the example below, the `paper.md` file is in the `paper` directory. Upon successful execution of the command, the `paper.pdf` file will be created in the same location as the `paper.md` file: - -```text -docker run --rm \ - --volume $PWD/paper:/data \ - --user $(id -u):$(id -g) \ - --env JOURNAL=joss \ - openjournals/inara -``` - -### Locally - -The materials for the `inara` container image above are themselves open source and available in [its own repository](https://github.com/openjournals/inara). You can clone that repository and run the `inara` script locally with `make` after installing the necessary dependencies, which can be inferred from the [`Dockerfile`](https://github.com/openjournals/inara/blob/main/Dockerfile). - -## Submitting your paper +### Submitting your paper Submission is as simple as: - Filling in the [short submission form](http://joss.theoj.org/papers/new) - Waiting for the managing editor to start a pre-review issue over in the JOSS reviews repository: https://github.com/openjournals/joss-reviews -## No submission fees +### No submission fees There are no fees for submitting or publishing in JOSS. You can read more about our [cost and sustainability model](http://joss.theoj.org/about#costs). -## Preprint Policy - -Authors are welcome to submit their papers to a preprint server ([arXiv](https://arxiv.org/), [bioRxiv](https://www.biorxiv.org/), [SocArXiv](https://socopen.org/), [PsyArXiv](https://psyarxiv.com/) etc.) at any point before, during, or after the submission and review process. - -Submission to a preprint server is _not_ considered a previous publication. - -## Authorship - -Purely financial (such as being named on an award) and organizational (such as general supervision of a research group) contributions are not considered sufficient for co-authorship of JOSS submissions, but active project direction and other forms of non-code contributions are. The authors themselves assume responsibility for deciding who should be credited with co-authorship, and co-authors must always agree to be listed. In addition, co-authors agree to be accountable for all aspects of the work, and to notify JOSS if any retraction or correction of mistakes are needed after publication. - -## Submissions using proprietary languages/development environments - -We strongly prefer software that doesn't rely upon proprietary (paid for) development environments/programming languages. However, provided _your submission meets our requirements_ (including having a valid open source license) then we will consider your submission for review. Should your submission be accepted for review, we may ask you, the submitting author, to help us find reviewers who already have the required development environment installed. -## The review process +## Review Process After submission: From 015892b391477d98e7660ac1b258cf525db4d2b8 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 16 Apr 2024 19:48:05 -0600 Subject: [PATCH 2/2] fix eval-rst --- docs/paper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper.md b/docs/paper.md index 4440a736..643accdd 100644 --- a/docs/paper.md +++ b/docs/paper.md @@ -264,7 +264,7 @@ Software should use an OSI-approved license. The above example results in the following output: -> ```{eval_rst} +> ```{eval-rst} > > Articles are published under a Creative Commons license [#f1]_. Software should use an OSI-approved license. >