8127 citation field improvements

[jggautier]

This pull request has been reverted by PR #8557

What this PR does / why we need it:
This PR makes grammar, style and consistency improvements to the titles, descriptions/tooltips and watermarks of all metadata fields that appear in the Citation metadata block.

This includes edits to fields that appear in the Citation Metadata accordions (controlled by the citation.tsv and citation.properties files) and whose values are system-generated, like the Dataset Persistent ID, Previous Dataset Persistent ID, and Publication Date fields (controlled by the bundles.properties file).

The changes should provide clearer information to curators, depositors, and people looking for data about what the fields are for.

It also adds a new page in the Style Guides called "Text" that includes a section called "Metadata Text Guidelines", which includes a link to the Google Doc where the guidelines are being maintained for now since we expect them to be revised frequently.

Which issue(s) this PR closes:
Closes #8127

Special notes for your reviewer:

Suggestions on how to test this:
Reload the Citation metadatablock. See the Reloading a Metadata Block section of the Admin guide.

Create and edit a dataset to spot check that the titles, descriptions/tooltips and watermarks of fields shown on the following pages have changed:

• Dataset page when creating, editing and viewing a dataset
• Search page facet categories
• Advanced search page
• Dataverse edit page (in the Metadata Fields and Browse/Search Facets sections)

The spreadsheet at https://docs.google.com/spreadsheets/d/1sHRvSpGSF0XfKTp4nWxT0zX4z8TORcuX7DTDrktOorg shows what the field titles, tooltips and watermarks were and, if they've been changed, how they've been changed. I wouldn't suggest checking all changes, since every description/tooltip has been edited. I hope checking a few on each page would be enough to spot any problems.

Check the Style Guide to make sure its Contents list includes a link to the "Text" page and check that clicking on that link takes you to the Text page, which should include a "Metadata Text Guidelines" section.

Does this PR introduce a user interface change? If mockups are available, please link/include them here:
Yes, the mockups below show some of the changes to the field titles and watermarks. The tooltips are shy (they appear only one at a time when hovering over or touching them) so it's tougher to show their changes in the same way, but all of the changes can be seen in the spreadsheet at https://docs.google.com/spreadsheets/d/1sHRvSpGSF0XfKTp4nWxT0zX4z8TORcuX7DTDrktOorg.

Below those images are mockups of the changes to the Style Guide.

Mockups of changes to the Style Guides page

Is there a release notes update needed for this change?:
Yes, I think the changes should be mentioned. In addition to the summary in this comment, we have a lot of content in the style guide that I think could be used to describe the changes.

[jggautier]

In addition to changes to the field names, titles, and watermarks, a guidelines document is being added in a new page called "Text" in the Style Guide. The guidelines are being maintained in a Google Doc now, and the new "Text" page will include a link to that Google Doc.

To start those changes, I've created and edited RST files in the 8127-citation-field-improvements branch, but the link to the Google Doc may change. When we're done organizing the content in the Google Doc, we'll make sure the link to it in the "Text" page points to the right Google Doc.

[jggautier]

The Style Guide "Text" page is updated. I moved this PR to the review column.

[pdurbin]

What about upgrades?

Should "Suggestions on how to test this" talk about reloading the citation.tsv file?

Should a release note be added about reloading the citation.tsv file?

[jggautier]

Thanks. In the "Suggestions on how to test this" section I added info about reloading the metadatablock.

The release notes for v5.4 have info about reloading the Citation metadatablock in the release notes' "Notes for Dataverse Installation Administrators" section and item number 9 in the "Upgrade Instructions" section.

[kcondon]

When I attempt to add the citation.tsv I get this command line error:
curl http://localhost:8080/api/admin/datasetfield/load -H "Content-type: text/tab-separated-values" -X POST --upload-file /tmp/citation.tsv
{"status":"ERROR","message":"Error parsing metadata block in DATASETFIELD part, line #82: No enum constant edu.harvard.iq.dataverse.DatasetFieldType.FieldType.DISPLAYORDER"}

[jggautier]

I think I fixed the issue. There was an extra tab on line 82. Not sure how it got there.

[jggautier]

Okay, release notes have been added. The wget command included has placeholder text where the version number should be (wget https://github.com/IQSS/dataverse/releases/download/v#.##/citation.tsv) since it looks like the version number should be the Dataverse software version that the change will occur in, which for now is unknown.

I'm removing myself as an assignee on this PR but let me know how else I can help.

[jggautier]

Hey all. This PR is marked as merged even though it was unmerged. Is that okay? For example, will it still be able to be tracked on the project board at https://github.com/orgs/IQSS/projects/2? Apologies if I missed any conversation about the status of this PR (other than Jim's thoughts at #8533 (comment))

[qqmyers]

Once I put a fix in for #8533, I think we'll either need to remerge this or have a new PR for the same change.

[pdurbin]

I checked with @qqmyers and created a new issue about how we want the Semantic Metadata API to be tolerant of changes to human readable labels (like "Contact" changing to "Point of Contact"):

• Semantic Metadata API can break when labels are changed (e.g. Contact -> Point of Contact) #8590

I also talked to @jggautier and suggested that he hold off on creating a new pull request for the changes he wants until that API is fix. I'm saying new pull request because I think that's easier/cleaner from the git perspective. On a related note, I just reopened #8127 (and removed the 5.10.1 milestone). I figure the new PR will be marked to close (re-close) that issue.