Submit via form

[noamross]

@karthik has done some testing on submitting an issue via a form to automatically populate the issue with more standardized input. If we agree it's a good idea, we can move towards having form-based submittal so that we have issues that are easier to parse and simpler to read.

This should probably "launch" along with the gitbook and new onboarding landing page.

To-Dos:

• Form
  • With logic for JOSS/MEE submittal
  • With automatic confirmation message to author(s) with link to the issue
• A separate form for a pre-submittal inquiry.
• Prominent links to the submittal form in the onboarding landing page (and elsewhere?)
• An R function in the rodev package for submission?
• What else?

I'm not sure whether this should assign to a default editor. If, so it would be the current EiC.

[maelle]

I'm trying to see how it'd work with a function. Right now I can only see two distinct submission methods: either Typeform+clicking or submission without the form via a YAML template. If authors fill a YAML (YAML use idea credit goes to @karthik ), they have the submission content under version control and some fields could be pre-filled by using package metadata (and I think @karthik mentioned interactive questioning as well). In that case this issue here is

• create a new submission template

• have a corresponding Typeform form

• have a corresponding function in rodev, using one of GitHub APIs (so opening an issue using the same template but via GitHub API directly, and with confirmation as a message in the console / with a browse option like gistr offers when creating gists).

I wouldn't use a separate form for a pre-submittal enquiry but rather Typeform logic. As regards the template use via rodev: we could have the template live somewhere e.g. ropensci/onboarding and a rodev function would access and download and prepare (i.e. use pre-sub or submission fields) the template when the author call prepare_submission or prepare_presub_enquiry. I'd like rodev to download the template anew this way the template used will always be up-to-date no matter the rodev version used.

Would we forbid submission outside of rodev/Typeform? Technically, how? Or maybe we wouldn't but we could have a bot checking the format of the issue just opened, and if it's badly formatted, it'd tell people to use the template or to open an issue in onboarding-meta if their goal was to make a general comment?

Template(s) notes

• putting DESCRIPTION inside <details> blabla </details>?

• changing the order of the fields at the same time, which was something @karthik mentioned

Last point, there's no way to automatically create a Typeform form from a YAML, is there? I mean to create the form "template", not from an submitting author perspective.

[maelle]

The prepare_submission function would also digest the MEE/JOSS fields depending on a journal argument.

[maelle]

Btw dup of https://github.com/ropensci/onboarding-meta/issues/29.

[maelle]

In that other issue @noamross wrote "Certain checkmarks would have to be checked to submit". I imagine that for the form it'd be self-assessment e.g saying yes to "Did you blabla?"

[karthik]

I'm trying to see how it'd work with a function. Right now I can only see two distinct submission methods: either Typeform+clicking or submission without the form via a YAML template. If authors fill a YAML (YAML use idea credit goes to @karthik ), they have the submission content under version control and some fields could be pre-filled by using package metadata (and I think @karthik mentioned interactive questioning as well).

All three methods would work well with each other. We need to standardize a template first. The same template will go in:

• The github pipe from typeform → issue.
• The example yml
• The interactive questionaire

With the user maintained yml, we might ask them to prune manually (i.e. remove JOSS or MEE when not appropriate).

putting DESCRIPTION inside

blabla

I thought about that but decided against it, because:

• I was the one that originally put in the request for details within code blocks for onboarding submissions. My rationale was that we could do some quick visual triage of what dependencies people were using and help out early. But that pre-dates gp.
• Something within <details> would just be html to parse, which doesn't make much sense when we are now moving everything to key-value pairs. We can query the DESCRIPTION file directly, or link to it via template for an editor to inspect (that way it's not a static version at submit time).

[karthik]

Other useful things we can do:

• Authors can choose categories
• Authors can recommend reviewers (we can pre-populate list from our list of handles + allow free form suggestions in the same box. We would update this list periodically)

[maelle]

Optimally we'd ask them to have categories in DESCRIPTION via schema.org terms

[maelle]

what about an RStudio addin helping fill the YAML. I.e. no typeform at all, just an addin, so one could use an RStudio addin or fill a YAML opened by a function (YAML that'd have some fields pre-filled, even when it's just opened by the function prepare_submission()).

related rodev issue https://github.com/ropensci/rodev/issues/2

[noamross]

I like the Add-in or maybe a devtools::release()-like flow that's IDE-agnostic. I would want to avoid the data being stored as a file in the repo - I think there are too many such files., Hmm, thinking about it maybe inst/ropensci-submit.yml is OK. A function in the package could validate it.

[maelle]

devtools::release() workflow tests https://github.com/ropensci/rodev/pull/40 (nothing done with an addin... yet)

• Having this and/or a form means keeping the submission template in two places (as an issue template, and somewhere else in a slightly different format)
• I would prefer to prepare my submission in a file locally to have other authors comment on it etc. as opposed to storing text somewhere and then using a form but I see the value in the submission by a form.

[maelle]

@karthik in https://github.com/ropensci/software-review-meta/issues/51#issuecomment-384338189 you mention suggesting handles from our reviewer database but I don't think we can do that, since it'd make our data partly public?

[karthik]

Yes let's skip that.

[maelle]

Important point made by @karthik in a Google Doc "The web form and interactive helper can tell people what this is if they dont know and if they have no tests to stop the submission process and go fix. Same for CI."

I hope GitHub issue forms will have that kind of logic.

[maelle]

Apparently I didn't write down anything from @mpadge's and my tests of GitHub issue forms. They did not play well with our use of HTML comments for buffy. If we wanted to support submission via a form, we'd need to implement something of our own.

[maelle]

saw https://new-issue.vuejs.org/?repo=vuejs%2Fcore (for inspiration?)