Merge branch 'develop' into model-run-workflow

.github/PULL_REQUEST_TEMPLATE.md

@@ -26,6 +26,9 @@
 <!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
 - [ ] My change requires a change to the documentation.
 - [ ] My name is in the list of CITATION.cff
+- [ ] I agree that PEcAn Project may distribute my contribution under any or all of
+	- the same license as the existing code,
+	- and/or the BSD 3-clause license.
 - [ ] I have updated the CHANGELOG.md.
 - [ ] I have updated the documentation accordingly.
 - [ ] I have read the **CONTRIBUTING** document.

.github/workflows/stale.yml

@@ -8,10 +8,15 @@ jobs:
   stale:
     if: github.repository == 'PecanProject/pecan'
 
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/stale@v6
+    - uses: actions/stale@v9
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         stale-issue-message: 'This issue is stale because it has been open 365 days with no activity.'

CHANGELOG.md

@@ -21,6 +21,7 @@ For more information about this file see also [Keep a Changelog](http://keepacha
     * Model packages `PEcAn.BASGRA`, `PEcAn.CLM45`, `PEcAn.DALEC`, `PEcAn.dvmdostem`, `PEcAn.FATES`, `PEcAn.GDAY`, `PEcAn.JULES`, `PEcAn.LDNDC`, `PEcAn.LINKAGES`, `PEcAn.LPJGUESS`, `PEcAn.MAAT`, `PEcAn.MAESPA`, `PEcAn.PRELES`, `PEcAn.SIBCASA`, `PEcAn.SIPNET`, `PEcAn.STICS`, and the new model package template.
     * Modules `PEcAn.allometry`, `PEcAn.assim.batch`, `PEcAn.data.mining`, `PEcAn.emulator`, `PEcAn.MA`, `PEcAn.photosynthesis`, `PEcAn.priors`, and `PEcAn.RTM`.
 - Renamed master branch to main
+- `PEcAn.all::pecan_version()` now reports commit hashes as well as version numbers for each installed package.
 
 ### Removed
 

CONTRIBUTING.md

@@ -110,6 +110,10 @@ git push -u origin GH-issuenumber-title-of-issue
 
  When finished create a pull request from your branch to the main pecan repository.
 
+ When submitting a pull request, you retain authorship of the code you contribute. However, you are giving the PEcAn Project permission to distribute your contributions under either or both, at our discretion, of:
+  - The license listed at PR opening time for the code you are contributing to,
+  - and/or the BSD 3-clause license.
+
 ## Additional Resources
 
 - [Adding models to PEcAn](https://pecanproject.github.io/pecan-documentation/latest/adding-an-ecosystem-model.html)

Makefile

@@ -67,13 +67,19 @@ drop_parents = $(filter-out $(patsubst %/,%,$(dir $1)), $1)
 # Generates a list of regular files at any depth inside its argument
 files_in_dir = $(call drop_parents, $(call recurse_dir, $1))
 
+# Git hash + clean status for this directory
+git_rev = $(shell \
+	CLEAN=$$([[ -n $$(git status -s $1) ]] && echo "+mod"); \
+	echo $$(git rev-parse --short=10 HEAD)"$$CLEAN")
+
 # HACK: NA vs TRUE switch on dependencies argument is an ugly workaround for
 # a circular dependency between benchmark and data.land.
 # When this is fixed, can go back to simple `dependencies = TRUE`
 depends_R_pkg = ./scripts/time.sh "depends ${1}" ./scripts/confirm_deps.R ${1} \
 	$(if $(findstring modules/benchmark,$(1)),NA,TRUE)
 install_R_pkg = ./scripts/time.sh "install ${1}" Rscript \
 	-e ${SETROPTIONS} \
+	-e "Sys.setenv(PECAN_GIT_REV='$(call git_rev,$1)')" \
 	-e "remotes::install_local('$(strip $(1))', force=TRUE, dependencies=FALSE, upgrade=FALSE)"
 check_R_pkg = ./scripts/time.sh "check ${1}" Rscript scripts/check_with_errors.R $(strip $(1))
 test_R_pkg = ./scripts/time.sh "test ${1}" Rscript \
@@ -132,12 +138,6 @@ $(subst .doc/models/template,,$(MODELS_D)): .install/models/template
 ### Order-only dependencies
 # (i.e. prerequisites must exist before building target, but
 # target need not be rebuilt when a prerequisite changes)
-
-.doc/base/all: | $(ALL_PKGS_D)
-.install/base/all: | $(ALL_PKGS_I)
-.check/base/all: | $(ALL_PKGS_C)
-.test/base/all: | $(ALL_PKGS_T)
-
 include Makefile.depends
 
 clean:

base/all/DESCRIPTION

@@ -1,7 +1,6 @@
 Package: PEcAn.all
 Type: Package
-Title: PEcAn functions used for ecological forecasts and
-    reanalysis
+Title: PEcAn Functions Used for Ecological Forecasts and Reanalysis
 Version: 1.8.0.9000
 Authors@R: c(person("Mike", "Dietze", role = c("aut"),
                      email = "[email protected]"),

base/all/NAMESPACE

@@ -1,3 +1,4 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(print,pecan_version_report)
 export(pecan_version)

base/all/NEWS.md

@@ -3,6 +3,10 @@
 ## License change
 * PEcAn.all is now distributed under the BSD three-clause license instead of the NCSA Open Source license.
 
+## Changed
+* `pecan_version()` now reports the Git revision (if known) for each package,
+  and prints its results more compactly for easier reading.
+
 # PEcAn.all 1.8.0
 
 ## Added

base/all/R/pecan_version.R

@@ -23,9 +23,9 @@
 #' @param exact Show only tags that exactly match `version`,
 #'  or all tags that have it as a substring?
 #' @return data frame with columns for package name, expected version(s),
-#'  and installed version.
-#'  If the `sessioninfo` package is installed, a fourth column reports where
-#'  each package was installed from: local, github, CRAN, etc.
+#'  installed version, and Git hash (if known).
+#'  If the `sessioninfo` package is installed, an additional column reports
+#'  where each package was installed from: local, github, CRAN, etc.
 #'
 #' @examples
 #' pecan_version()
@@ -46,7 +46,7 @@ pecan_version <- function(version = max(PEcAn.all::pecan_releases$version),
     )
     version <- unique(unlist(version))
   }
-  cols_to_return <- c("package", version, "installed")
+  cols_to_return <- c("package", version, "installed", "build_hash")
 
 
   if (requireNamespace("sessioninfo", quietly = TRUE)) {
@@ -55,23 +55,24 @@ pecan_version <- function(version = max(PEcAn.all::pecan_releases$version),
     all_pkgs <- sessioninfo::package_info(pkgs = "installed", dependencies = FALSE)
     our_pkgs <- all_pkgs[grepl("PEcAn", all_pkgs$package),]
 
+    # Why do we need this when `pkgs = "installed"` usually shows loaded too?
+    # Because there are times a package is loaded but not installed
+    # (e.g. notably during R CMD check)
     all_loaded <- sessioninfo::package_info(pkgs = "loaded", dependencies = FALSE)
     our_loaded <- all_loaded[grepl("PEcAn", all_loaded$package),]
 
-    unloaded <- our_pkgs[!our_pkgs$package %in% our_loaded$package,]
-    our_pkgs <- rbind(our_loaded, unloaded)
-    our_pkgs <- our_pkgs[order(our_pkgs$package),]
-
-
     # TODO: consider using package_info's callouts of packages where loaded and
     #   installed versions mismatch -- it's a more elegant version of what we
     #   were trying for with the "multiple rows for packages with multiple
     #   versions found" behavior.
-    our_pkgs$installed <- ifelse(
-      test = is.na(our_pkgs$loadedversion),
-      yes = our_pkgs$ondiskversion,
-      no = our_pkgs$loadedversion)
-    our_pkgs <- our_pkgs[, c("package", "installed", "source")]
+    our_pkgs <- merge(
+      x = our_pkgs[, c("package", "ondiskversion", "source")],
+      y = our_loaded[, c("package", "loadedversion", "source")],
+      by.x = c("package", "ondiskversion", "source"),
+      by.y = c("package", "loadedversion", "source"),
+      all = TRUE,
+      sort = TRUE)
+    colnames(our_pkgs) <- c("package", "installed", "source")
     our_pkgs$installed <- package_version(our_pkgs$installed)
 
   } else {
@@ -89,17 +90,24 @@ pecan_version <- function(version = max(PEcAn.all::pecan_releases$version),
       package = names(our_loaded),
       installed = sapply(our_loaded, `[[`, "Version"))
     our_loaded$installed <- package_version(our_loaded$installed)
-    our_pkgs <- merge(our_pkgs, our_loaded, all = TRUE)
+    our_pkgs <- merge(our_pkgs, our_loaded, all = TRUE, sort = TRUE)
+    our_pkgs <- our_pkgs[!duplicated(our_pkgs),]
   }
 
+  want_hash <- !is.na(our_pkgs$installed)
+  our_pkgs$build_hash[want_hash] <- sapply(
+    our_pkgs$package[want_hash],
+    get_buildhash)
 
   res <- merge(
     x = our_pkgs,
     y = PEcAn.all::pecan_version_history,
     all = TRUE)
-  res <- res[, cols_to_return]
+  res <- drop_na_version_rows(res[, cols_to_return])
+  rownames(res) <- res$package
+  class(res) <- c("pecan_version_report", class(res))
 
-  drop_na_version_rows(res)
+  res
 }
 
 # Remove rows where all versions are missing
@@ -108,3 +116,46 @@ drop_na_version_rows <- function(df) {
   stopifnot(colnames(df)[[1]] == "package")
   df[rowSums(is.na(df[, -1])) < ncol(df[, -1]), ]
 }
+
+
+# Look up git revision, if recorded, from an installed PEcAn package
+get_buildhash <- function(pkg) {
+  # Set if pkg was installed from r-universe or via install_github()
+  desc_sha <- utils::packageDescription(pkg, fields = "RemoteSha")
+  if (!is.na(desc_sha)) {
+    return(substr(desc_sha, 1, 10))
+  }
+  # Set if PECAN_GIT_REV was set during install (includes `make install`)
+  get0(".build_hash", envir = asNamespace(pkg), ifnotfound = NA_character_)
+}
+
+
+# print method for version
+# (Just to help it display more compactly)
+#' @export
+print.pecan_version_report <- function(x, ...) {
+
+  dots <- list(...)
+  if (is.null(dots$row.names)) { dots$row.names <- FALSE }
+  if (is.null(dots$right)) { dots$right <- FALSE }
+
+  xx <- as.data.frame(x)
+  # only print hash for dev versions
+  # (typically x.y.z.9000, but we'll use anything with a 4th version component)
+  skip_hash <- is.na(xx$installed[,4]) | is.na(xx$build_hash)
+  xx$build_hash[skip_hash] <- ""
+  xx$build_hash <- sub(".{4}\\+mod$", "+mod", xx$build_hash)
+  xx$installed <- paste0(
+    xx$installed,
+    sub("(.+)", " (\\1)", xx$build_hash))
+  xx$build_hash <- NULL
+  if (!is.null(xx$source)) {
+    xx$source <- paste0(
+      strtrim(xx$source, 17),
+      ifelse(nchar(xx$source, type="width") <= 17, "", "..."))
+  }
+  dots$x <- xx
+  do.call("print", dots)
+
+  invisible(x)
+}

base/all/R/version.R

@@ -0,0 +1,3 @@
+# Set at package install time, used by pecan.all::pecan_version()
+# to identify development versions of packages
+.build_hash <- Sys.getenv("PECAN_GIT_REV", "unknown")

base/all/data/pecan_version_history.R

@@ -1,25 +1,34 @@
 
+# Read and format a list of pecan versions
 
-pecan_version_history <- utils::read.csv(
-  "pecan_version_history.csv",
-  colClasses = "character",
-  check.names = FALSE)
+# The local() wrapper is to avoid adding objects to the package data:
+# Any extra vars defined at the top level of this file would be loaded
+# into the global environment by `data("pecan_version_history")`
 
-# We'd like to parse strictly to catch invalid versions (probably typos).
-# But we _need_ to allow NAs... and in R < 4.4, package_version did not
-# accept NAs unless strict=FALSE.
-strict <- TRUE
-na_version <- try(
-  package_version(NA_character_, strict = strict),
-  silent = TRUE)
-if (inherits(na_version, "try-error")) {
-  strict <- FALSE
-}
+pecan_version_history <- local({
+  pvh <- utils::read.csv(
+    "pecan_version_history.csv",
+    colClasses = "character",
+    check.names = FALSE)
 
-for (col in colnames(pecan_version_history)) {
-  if (col != "package") {
-    pecan_version_history[[col]] <- package_version(
-      pecan_version_history[[col]],
-      strict = strict)
+  # We'd like to parse strictly to catch invalid versions (probably typos).
+  # But we _need_ to allow NAs... and in R < 4.4, package_version did not
+  # accept NAs unless strict=FALSE.
+  strict <- TRUE
+  na_version <- try(
+    package_version(NA_character_, strict = strict),
+    silent = TRUE)
+  if (inherits(na_version, "try-error")) {
+    strict <- FALSE
   }
-}
+
+  for (col in colnames(pvh)) {
+    if (col != "package") {
+      pvh[[col]] <- package_version(
+        pvh[[col]],
+        strict = strict)
+    }
+  }
+
+  pvh
+})

base/all/tests/Rcheck_reference.log

@@ -14,38 +14,6 @@ New submission
 
 Version contains large components (1.7.2.9000)
 
-License components with restrictions and base license permitting such:
-  BSD_3_clause + file LICENSE
-File 'LICENSE':
-  University of Illinois/NCSA Open Source License
-
-  Copyright (c) 2012, University of Illinois, NCSA.  All rights reserved.
-
-  Permission is hereby granted, free of charge, to any person obtaining
-  a copy of this software and associated documentation files (the
-  "Software"), to deal with the Software without restriction, including
-  without limitation the rights to use, copy, modify, merge, publish,
-  distribute, sublicense, and/or sell copies of the Software, and to
-  permit persons to whom the Software is furnished to do so, subject to
-  the following conditions:
-
-  - Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimers.
-  - Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimers in the
-    documentation and/or other materials provided with the distribution.
-  - Neither the names of University of Illinois, NCSA, nor the names
-    of its contributors may be used to endorse or promote products
-    derived from this Software without specific prior written permission.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-  IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR
-  ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
-  CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE.
-
 Strong dependencies not in mainstream repositories:
   PEcAn.DB, PEcAn.settings, PEcAn.MA, PEcAn.logger, PEcAn.utils,
     PEcAn.uncertainty, PEcAn.data.atmosphere, PEcAn.data.land,
@@ -54,13 +22,6 @@ Strong dependencies not in mainstream repositories:
 Suggests or Enhances not in mainstream repositories:
   PEcAn.ED2, PEcAn.SIPNET, PEcAn.BIOCRO, PEcAn.DALEC, PEcAn.LINKAGES,
     PEcAn.allometry, PEcAn.photosynthesis
-
-The Title field should be in title case. Current version is:
-‘PEcAn functions used for ecological forecasts and reanalysis’
-In title case that is:
-‘PEcAn Functions Used for Ecological Forecasts and Reanalysis’
-
-The Date field is over a month old.
 * checking package namespace information ... OK
 * checking package dependencies ... NOTE
 Depends: includes the non-default packages: