Difference between revisions of "UCVM Release Planning"

From SCECpedia
Jump to navigationJump to search
 
(53 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Key UCVM Improvements: ==
+
== Updated UCVM Documentation ==
#Convergence of versions
+
*[https://github.com/sceccode/ucvm/wiki UCVM Wiki]
#Large files next release stored on S3
+
**[UCVM README.md]
#CI setup
+
*[https://github.com/sceccode/ucvm_docker/wiki UCVM Docker Wiki]
#Documentation Updated into new structure
+
**[UCVM Docker README.md]
#Tests output
+
*[https://github.com/sceccode/ucvm_plotting/wiki UCVM Plotting Wiki]
#Code Metadata included in repo
+
**[UCVM Plotting READM.md]
#Tags from USGS Thesarus
 
#Post DOI badge on UCVM
 
#Test with singularity on an XSEDE system
 
#UCVM Communitee
 
#Code of Conduct
 
#Open Source Metrics setup
 
#Code coverage statements
 
#Identification of sub-licenses in distribution
 
#Authorship contributions noted
 
  
== Standard Contents of Git repo: ==
+
== Citable Code ==
#A README with pictures/gifs of the product in action and a nice logo.
+
*[https://guides.lib.berkeley.edu/citeyourcode Make UCVM Citable]
#Documentation.
 
#Code QA (Static Code Analysis).
 
#Contributing instructions.
 
#A well-defined setup section.
 
#Support (Respond to Issues/PR)
 
#Publish software news in every possible way.
 
  
== Contents of README.md ==
+
== UCVM Tests Organization ==
When someone is looking at your project, they want to know:
+
A set of C language tests are defined as Unittests:
# what is it?
+
*[[UCVM Testing]]
# how good the code is?
 
# how much support is available?
 
# what’s included?
 
# what does it look like?
 
# how set it up?
 
  
== Science Code Manifesto Elements: ==
+
UCVM Programs found in the ucvm source code directory contains numerous example programs that are not included in the ucvm_bin installation directory. A list of programs in the UCVM Source directory is given here:
# Code
+
*[[UCVM Examples]]
# Copyright
 
# Citation
 
# Credit
 
# Curation
 
  
== Steps To Software Product: ==
+
UCVM Plotting routines have been moved into a separate repo. Information on the plotting routines.
1. Create citable, definitive version of software with doi, license, and repository.
+
*[[UCVM Plotting]]
2. Define reference publication used to cite software.
 
3. Define software as reference implementation of a method, and define a set of approved software acceptance/regression tests that can be used to establish a software implements that “method”.
 
4. Create software maintenance organization with commit authority for pull requests and approval process for change requests, and process of approving new releases.
 
5. Establish software community through registrations, newsletters, activity, regular calls, regular meetings, define community and roles.
 
  
== Adoption of Fork and Pull Git Repo Model ==
+
== ToDo ==
* Use the model used by the majority of open-source projects (including pyCSEP).
 
* The “maintainer” of the shared repo assigns rights to “Collaborators”
 
* Collaborators do not have push access to main (upstream) repo
 
* Core development teams accepts (PRs) from collaborators, reviews them, then merges them into main repo
 
  
== Contributor Process: ==
+
* Document the scripts in ucvm/utilities
Working with shared projects on GitHub
+
* Update the version numbers from 21.7 in get_largefiles.py and check_large_files.py
1. Fork the repository
+
* fix version in setup.list
2. Clone your forked copy
+
* confirm that models are correctly un-commented in ucvm.conf file (seems like cvm-H and others were not enabled)
3. Sync your personal repo with shared repo
+
* Check references to proj-4 in documentation and code error messages and update if necessary to proj-5
a. Git merge/git rebase
+
* Check ucvm/tests/Makefile.am setting, but never using, AM_CFLAGS
4. Make a contribution
+
* change, or explain to users, two different ucvm.conf in the system
a. Pull request
 
  
== How we want it Cited: ==
 
* Example Citation:
 
* Example Acknowledgements:
 
* Example Reference:
 
  
== Basic Recommendations: ==
+
== Key UCVM Improvements in 21.10 release: ==
1. Make source code publicly accessible
+
* Move the run_ucvm.sh and run_ucvm_query.sh script to utilities
2. Make software easy to discover by providing software metadata via a popular community registry (Examples of community registries of software metadata are bio.tools (Ison et al., 2016), (Ison et al., 2016) biojs.io (Corpas et al.,2014; Gómez et al., 2013) and Omic Tools (Henry et al., 2014) in the life sciences and DataCite (Brase, n.d.) as a generic metadata registry for software as well as data.
+
*Convergence of versions
3. Adopt a license and comply with the license of third party dependencies
+
** Used updated version used UCVM website
4. Define clear and transparent contribution, governance and communications processes (For instance the Galaxy project’s website describes the team’s structure, how to be part of the community, and their communication channels.)
+
** Combined source codebase web version and distributed version/command line version
 +
** reduce number of UCVM versions that we need to maintain
 +
*Large files next release stored on S3
 +
** Should improve download speed and reliability of install
 +
*CI setup
 +
** Review the CI for sceccode/ucvm before release
 +
*Documentation Updated into new structure
 +
** Re-organized to match recommended types of docs
 +
*Tests updated
 +
** combined c-language tests into unittest.
 +
* Code Metadata included in repo
 +
** added metadata to repo
 +
* Used Tags from USGS Thesarus for metadata
 +
* Post DOI badge on UCVM
 +
* UCVM Community developments encouraged
 +
** Add Code of Conduct document into repo
 +
** Added "contributor instructions" into README.md
 +
* Open Source Metrics setup (registered users, downloads, tags, visits)
 +
* Identification of sub-licenses in distribution
 +
* Velocity models stored in standalone repositories
 +
* Authorship contributions noted
 +
* add cv
 +
* add iv
 +
* add albacore
 +
* add utah wasatch front
 +
* projection code fix
 +
* Install using Dockerhub
 +
* Review issues that were done.
 +
* Added UCVM Website data plotting tools
  
== Types of Documentation with axis: ==
+
TBD
help learning – help working and theoretical knowledge – practical knowledge
+
* Test with both Docker and singularity on an XSEDE system
1. tutorials  - learning oriented
+
* Code coverage statements
2. how-to guides – task-oriented
 
3. Background/Concept explanations – understanding-oriented
 
4. technical reference – information-oriented
 
 
 
 
 
== DOCUMENTATION TYPES ==
 
* CODE DOCUMENTATION - Semantic identifiers, comments, API, engineering, dependencies, requirements
 
* USER DOCUMENTATION - How to get, run, use the software; parameters, data model, etc.; license
 
* MAINTENANCE DOCUMENTATION - How to build, release, review code, publish
 
* DEVELOPER DOCUMENTATION - How to contribute, contribution templates (issues, pull/merge requests)
 
* METADATA - Software metadata (CodeMeta), Citation File (CFF), "references" (dependencies)
 
* PROJECT DOCUMENTATION - Rationale, teams, governance, community (contact, code of conduct)
 
 
 
== Where Documentation Lives ==
 
Documentation lives where the source code lives! (This is never in an email, chat, or similar!)
 
Conceptual Documentation:
 
* Requirements
 
* Projects
 
Hands-on documentation
 
* How-tos, getting started
 
* Templates for issues, pull/merge
 
* Contribution guidelines
 
Reference documentation
 
* API
 
* Tests
 
* Metadata
 
 
 
== Toolbox Documentation: ==
 
Toolbox documentation should describe the steps off analysis in a pedagogical, narrative
 
fashion, with example data that users can load to follow along with and understand the documentation.
 
 
 
== Implement Multiple Test Types: ==
 
1. Functional testing – Unit Tests
 
2. Integration Testing – Testing interoperability of units
 
3. Acceptance testing – Results on user’s system equivalent to results on development system
 
4. Regression testing – Confirm equivalent results to previous results.
 
 
 
== Recommended Basic Practices: ==
 
1. Training on Software Practices
 
2. Code in a Code Repo
 
3. Automated Testing
 
4. Persistent ID for software versions
 
  
 
== UCVM Versus CIG Standards: ==
 
== UCVM Versus CIG Standards: ==

Latest revision as of 02:22, 4 November 2021

Updated UCVM Documentation

Citable Code

UCVM Tests Organization

A set of C language tests are defined as Unittests:

UCVM Programs found in the ucvm source code directory contains numerous example programs that are not included in the ucvm_bin installation directory. A list of programs in the UCVM Source directory is given here:

UCVM Plotting routines have been moved into a separate repo. Information on the plotting routines.

ToDo

  • Document the scripts in ucvm/utilities
  • Update the version numbers from 21.7 in get_largefiles.py and check_large_files.py
  • fix version in setup.list
  • confirm that models are correctly un-commented in ucvm.conf file (seems like cvm-H and others were not enabled)
  • Check references to proj-4 in documentation and code error messages and update if necessary to proj-5
  • Check ucvm/tests/Makefile.am setting, but never using, AM_CFLAGS
  • change, or explain to users, two different ucvm.conf in the system


Key UCVM Improvements in 21.10 release:

  • Move the run_ucvm.sh and run_ucvm_query.sh script to utilities
  • Convergence of versions
    • Used updated version used UCVM website
    • Combined source codebase web version and distributed version/command line version
    • reduce number of UCVM versions that we need to maintain
  • Large files next release stored on S3
    • Should improve download speed and reliability of install
  • CI setup
    • Review the CI for sceccode/ucvm before release
  • Documentation Updated into new structure
    • Re-organized to match recommended types of docs
  • Tests updated
    • combined c-language tests into unittest.
  • Code Metadata included in repo
    • added metadata to repo
  • Used Tags from USGS Thesarus for metadata
  • Post DOI badge on UCVM
  • UCVM Community developments encouraged
    • Add Code of Conduct document into repo
    • Added "contributor instructions" into README.md
  • Open Source Metrics setup (registered users, downloads, tags, visits)
  • Identification of sub-licenses in distribution
  • Velocity models stored in standalone repositories
  • Authorship contributions noted
  • add cv
  • add iv
  • add albacore
  • add utah wasatch front
  • projection code fix
  • Install using Dockerhub
  • Review issues that were done.
  • Added UCVM Website data plotting tools

TBD

  • Test with both Docker and singularity on an XSEDE system
  • Code coverage statements

UCVM Versus CIG Standards:

Minimum:

  • Version control – ok
  • Code – ok
  • Portable – ok
  • Testing – (a) tests that verify it runs properly (b) accuracy or benchmark tests
  • Documentation – (a) install (b) parameters (c) physics (d) example inputs cookbooks (e) citable pub
  • Userworkflow – ok

Standard:

  • Version control -ok
  • Coding – (a) params at runtime (b) development plan (c) code comments (d) add features without modify main branch (e) useful error reports
  • Portability: (a) dependency cheking (b) automake (c) output configuration and build options
  • Testing – pass fail tests
  • Documentation: (a) workflow for research (b) how to extend code
  • Userworkflow: (a) easy to change sim params (b) user specific directories/filenames for i/o (c) standard binary formats (d) citation for code version.