feat: update best practices for research software

user-guide/curating/bestpractices.md

@@ -85,15 +85,25 @@ Before publishing, ensure that:
 
 ### Research Software
 
-In alignment with [FAIR for Research Software (FAIR4RS) recommendations](https://www.nature.com/articles/s41597-022-01710-x), research software published in DDR should be feature complete and designed to be actively maintained, enhanced, and versioned. Whether published as Project Type "Other" or Project Type "Research Software", it should include sufficient documentation about its provenance (CodeMeta metadata) and how to use it (Readme).
+In alignment with [FAIR for Research Software (FAIR4RS) recommendations](https://www.nature.com/articles/s41597-022-01710-x) and [with our policies](/user-guide/curating/policies/#publishing-research-software), research software published in DDR should be feature complete and designed to be actively maintained, enhanced, and versioned. Whether published as Project Type "Other" or Project Type "Research Software", the publication should include documentation about the software's research role, functions,  and technical dependencies. The following are required best practices to publish research software:
 
-A [CodeMeta `json` file should be generated online](https://codemeta.github.io/codemeta-generator/) and uploaded to the GitHub repository, or uploaded along with the software files to Project Type “Other”. When filling the CodeMeta file, it is important to include as much information as possible, which allows for others to understand, reuse, and attribute your software.
+* A [CodeMeta json file should be generated online](https://codemeta.github.io/codemeta-generator/) and uploaded to the GitHub repository, or along with the software files to Project Type “Other”. When filling the CodeMeta file, it is important to include as much information as possible, which allows for others to understand, reuse, and attribute your software. Links to dependencies should be included in the Related Data and Software entry available in the metadata form. If allowed by their licenses, dependency files can and should be included as part of the publication package for ease of software installation.
+* A Readme file with details of how to install and use the software should also be part of the publication. To be reproducible, the software publication needs to include documentation about and  links to libraries and dependencies needed to run it. We ask researchers to test that the software can be installed according to instructions and that it is working properly at the time of publication.
+* Often researchers include data in their research software publications. Since Github is not a data repository, when using Project Type Research Software,  data can be published in DesignSafe using Project Type "Other," or another corresponding Project Type. Instead, if you use Project Type "Other" to publish Research Software, you can also include the data.
+* When present, the relation between the research software and the corresponding dataset should be indicated. From the research software publication, the dataset should be noted in the Related Work /linked entry available in the curation form. From the dataset publication, the research software should be related via the Referenced Data and Software/cites entry available in the curation form.  These linkages connect both publications, from data to software and vice versa. Linkages can be added after the data or the software have been published via Amends. The location of the dataset should also be  noted in the software Readme file.
 
-A Readme file including details of how to install and use the software should also be part of the publication. To be reproducible, the software publication needs to include documentation about, and  links to libraries and dependencies needed to run it. Links to dependencies can be noted in the Related Data and Software entry which is available in the . If allowed by their licenses, dependency files can and should be included as part of the publication package for ease of software installation. We ask researchers to test that the software can be installed according to instructions and that it is working properly at the time of publication.
+#### Versioning Research Software
 
-Many times users include or small subsets of data/demo files to their research software publications. Github is not a data repository so datasets should not be included in the Github repository. If the data cannot be published independently, software and data should be published as project type "Other". In that case, the source/provenance of the demo dataset should be noted in the Readme file and or pointed at in the Referenced Data and Software entry.
+* To version research software from Github, users should first create a new release in the software repository, update the URL in their dataset, and then proceed to version.
+* Changes in version number may not coincide between GitHub and DesignSafe. DesignSafe versioning is linear (e.g. `1`, `2`, `3`, …), while GitHub has a non-linear order (e.g. `1.10.5`, `2.0.0`). In addition a researcher may have many versions released in GitHub before they publish for the first time in DesignSafe. Consider that a "Software Release" field displayed in the metadata shows the release that has been published.
 
-##### Jupyter Notebooks as Research Software
+#### Adding Software Citation with DOI to GitHub Repository {#adding-citation-to-github-repo}
+
+Other users that access software from GitHub should have the opportunity to cite the research software using the formal citation with a DOI. For this, the DesignSafe citation including the DOI should be available in the GitHub repo.
+
+So, once the software is published in DesignSafe, researchers should [add the DesignSafe citation with DOI to the GitHub repo](/user-guide/curating/github-cite-this-repo/).
+
+### Jupyter Notebooks as Research Software
 
 If planning to publish a Jupyter Notebook in the DDR, the content must comply with the definition of research software available in the [Research Software Publication Policy](/user-guide/curating/policies/#publishing-research-software). Thus, the content of the Jupyter Notebook must be a contribution to solving a scientific problem. It should also comply with [Research Software Best Practices](#research-software) outlined above. 
 

user-guide/curating/policies.md

@@ -581,7 +581,7 @@ Below are the requirements for publishing research software in the DDR:
 * Prior to publishing, users agree that the software is functional and works according to the instructions provided in the readme file.
 * Research software should be self contained. While it should be possible to use the software with published data in DesignSafe or within DesignSafe Tools and Applications, it should not be written such that it is dependent on absolute file paths in DesignSafe data publications or on external file systems.
 * Research software publications should not include datasets. Instead datasets that are used by the research software for training, testing, validation, etc. should be published as a stand-alone datasets and linked to the research software publication via the Related Work/linked entry available in the curation form. In turn, a dataset can be related to the research software publication via the Referenced Data and Software/cites entry available in the curation form.
-* The citation and DOI obtained should be included in the GitHub repo and [show as Cite this Repository](/user-guide/curating/github-cite-this-repo/).
+* The citation and DOI obtained should be included in the GitHub repo and [add the DesignSafe citation with DOI to the GitHub repo](/user-guide/curating/bestpractices/#adding-citation-to-github-repo).
 * For guidance on publishing good quality research software, see [Research Software Best Practices](/user-guide/curating/bestpractices/#research-software).
 
 What does not qualify as research software: