Difference between revisions of "UCVM Release Planning"

From SCECpedia
Jump to navigationJump to search
 
(45 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== Fork and Pull Development ==
+
== Updated UCVM Documentation ==
−
Using the fork and pull method, start with fork of sceccode/ucvm.git into personal repo. Then, to do development on CARC, plan to clone pjmaechling/ucvm.git for development. Set git upstream to original repo sceccode/ucvm.git to keep in sync with that repo. Follow Instruction for setting upstream here:
+
*[https://github.com/sceccode/ucvm/wiki UCVM Wiki]
−
*[https://github.com/billtron/pycsep_git_tutorial Savran Git Tutorial]
+
**[UCVM README.md]
 +
*[https://github.com/sceccode/ucvm_docker/wiki UCVM Docker Wiki]
 +
**[UCVM Docker README.md]
 +
*[https://github.com/sceccode/ucvm_plotting/wiki UCVM Plotting Wiki]
 +
**[UCVM Plotting READM.md]
  
−
== Development on CARC ==
+
== Citable Code ==
−
* ssh -o "ServerAliveInterval 60" discovery.usc.edu
+
*[https://guides.lib.berkeley.edu/citeyourcode Make UCVM Citable]
−
* cd /project/scec_608/maechlin/dev
 
−
* git clone https://github.com/pjmaechling/ucvm.git
 
  
−
Start by adding codemeta.json file. Also add Contributors.MD file.
+
== UCVM Tests Organization ==
 +
A set of C language tests are defined as Unittests:
 +
*[[UCVM Testing]]
  
 +
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 Examples]]
  
−
== Key UCVM Improvements: ==
+
UCVM Plotting routines have been moved into a separate repo. Information on the plotting routines.
−
#Convergence of versions
+
*[[UCVM Plotting]]
−
#Large files next release stored on S3
 
−
#CI setup
 
−
#Documentation Updated into new structure
 
−
#Tests output
 
−
#Code Metadata included in repo
 
−
#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: ==
+
== ToDo ==
−
#A README with pictures/gifs of the product in action and a nice logo.
 
−
#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 ==
+
* Document the scripts in ucvm/utilities
−
When someone is looking at your project, they want to know:
+
* Update the version numbers from 21.7 in get_largefiles.py and check_large_files.py
−
# what is it?
+
* fix version in setup.list
−
# how good the code is?
+
* confirm that models are correctly un-commented in ucvm.conf file (seems like cvm-H and others were not enabled)
−
# how much support is available?
+
* Check references to proj-4 in documentation and code error messages and update if necessary to proj-5
−
# what’s included?
+
* Check ucvm/tests/Makefile.am setting, but never using, AM_CFLAGS
−
# what does it look like?
+
* change, or explain to users, two different ucvm.conf in the system
−
# how set it up?
 
  
−
== Science Code Manifesto Elements: ==
 
−
# Code
 
−
# Copyright
 
−
# Citation
 
−
# Credit
 
−
# Curation
 
  
−
== Steps To Software Product: ==
+
== Key UCVM Improvements in 21.10 release: ==
−
# Create citable, definitive version of software with doi, license, and repository.
+
* Move the run_ucvm.sh and run_ucvm_query.sh script to utilities
−
# Define reference publication used to cite software.
+
*Convergence of versions
−
# 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”.
+
** Used updated version used UCVM website
−
# Create software maintenance organization with commit authority for pull requests and approval process for change requests, and process of approving new releases.
+
** Combined source codebase web version and distributed version/command line version
−
# Establish software community through registrations, newsletters, activity, regular calls, regular meetings, define community and roles.
+
** 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
  
−
== Adoption of Fork and Pull Git Repo Model ==
+
TBD
−
* Use the model used by the majority of open-source projects (including pyCSEP).
+
* Test with both Docker and singularity on an XSEDE system
−
* The “maintainer” of the shared repo assigns rights to “Collaborators”
+
* Code coverage statements
−
* 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: ==
 
−
Working with shared projects on GitHub
 
−
# Fork the repository
 
−
# Clone your forked copy
 
−
# Sync your personal repo with shared repo
 
−
# Git merge/git rebase
 
−
# Make a contribution
 
−
# Pull request
 
−
 
 
−
== How we want it Cited: ==
 
−
* Example Citation:
 
−
* Example Acknowledgements:
 
−
* Example Reference:
 
−
 
 
−
== Basic Recommendations: ==
 
−
# Make source code publicly accessible
 
−
# 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.
 
−
# Adopt a license and comply with the license of third party dependencies
 
−
# 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.)
 
−
 
 
−
== Types of Documentation with axis: ==
 
−
* help learning – help working
 
−
* theoretical knowledge – practical knowledge
 
−
# tutorials  - learning oriented
 
−
# how-to guides – task-oriented
 
−
# Background/Concept explanations – understanding-oriented
 
−
# 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: ==
 
−
# Functional testing – Unit Tests
 
−
# Integration Testing – Testing interoperability of units
 
−
# Acceptance testing – Results on user’s system equivalent to results on development system
 
−
# Regression testing – Confirm equivalent results to previous results.
 
−
 
 
−
== Recommended Basic Practices: ==
 
−
# Training on Software Practices
 
−
# Code in a Code Repo
 
−
# Automated Testing
 
−
# 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.
Retrieved from "https://strike.scec.org/scecwiki/index.php?title=UCVM_Release_Planning&oldid=26164"