Release version 1.0.0

.editorconfig

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2020 Wolfgang Traylor <[email protected]>
+# SPDX-FileCopyrightText: 2020 W. Traylor <[email protected]>
 #
 # SPDX-License-Identifier: CC0-1.0
 

.gitignore

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2020 Wolfgang Traylor <[email protected]>
+# SPDX-FileCopyrightText: 2020 W. Traylor <[email protected]>
 #
 # SPDX-License-Identifier: CC0-1.0
 

.gitlab-ci.yml

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2020 Wolfgang Traylor <[email protected]>
+# SPDX-FileCopyrightText: 2020 W. Traylor <[email protected]>
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
@@ -24,6 +24,20 @@ check_license:
   script:
     - reuse lint
 
+# Check that the tag matches the version in the CMakeLists.txt file.
+# If the tag doesn’t match, you will need to change CMakeLists.txt and
+# forcefully move the tag to the corrected commit.
+check_version:
+  image: ubuntu:latest
+  stage: lint
+  rules:
+    # Only execute on tags that look like a version, e.g.: "0.5.1"
+    - if: '$CI_COMMIT_TAG =~ /^\d+\.\d+\.\d+.*/'
+      when: always
+  script:
+    - echo "If this fails, check that the Git tag matches VERSION in CMakeLists.txt."
+    - test "$CI_COMMIT_TAG" == $(grep "^\s*VERSION" CMakeLists.txt | grep -oP '\d+\.\d+\.\d+.*')
+
 compile:
   image: gcc:latest
   stage: build

.readthedocs.yaml

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2021 Wolfgang Traylor <[email protected]>
+#
+# SPDX-License-Identifier: CC0-1.0
+
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+   configuration: docs/sphinx/conf.py

CHANGELOG.md

@@ -12,6 +12,25 @@ The format is based on [Keep a Changelog][] by Olivier Lacan, and this project a
 [Keep a Changelog]: <https://keepachangelog.com/en/1.0.0/>
 [Semantic Versioning]: <https://semver.org/spec/v2.0.0.html>
 
+## [1.0.0] - 2021-04-26
+
+### Added
+- R scripts and LibreOffice document to reproduce figures in `docs/images/`. [#31]
+- Minor additions to docs.
+- Integration for [readthedocs.org](https://readthedocs.org)
+- CI check for Git tag matching version in CMakeLists.txt
+
+### Changed
+- Use sward density for `Fauna::HalfMaxIntake` (instead of whole-habitat grass density). This requires the vegetation model to provide correct “FPC” values (fractional area covered by grass in the habitat). [#12]
+- Use modern `rmarkdown` package to render demo results.
+
+### Fixed
+- Demo simulator has now monthly ambient air temperature.
+- Replace copyrighted figure `docs/images/thermoregulation.png` with my own. [#32]
+
+### Removed
+- Snow depth. It is not used anywhere. [#14]
+
 ## [0.6.0] - 2021-04-08
 
 ### Added
@@ -150,27 +169,30 @@ The format is based on [Keep a Changelog][] by Olivier Lacan, and this project a
 - Herbivores in cohort and individual mode.
     - Energy expenditure components:
         - Allometric
-        - Based on [Taylor et al. (1981)](http://journals.cambridge.org/article_S0003356100040617)
+        - Based on [Taylor et al. (1981)][]
         - Thermoregulation
     - Diet composer: only grass
     - Reproduction models:
         - Constant annual reproduction rate
-        - Based on [Illius & O’Connor (2000)](http://www.jstor.org/stable/3547323)
+        - Based on [Illius & O’Connor (2000)][]
         - Linear relationship with body condition
     - Mortality factors:
         - Constant annual background mortality
         - Death at end of lifespan
-        - Starvation mortality based on [Illius & O’Connor (2000)](http://www.jstor.org/stable/3547323)
+        - Starvation mortality based on [Illius & O’Connor (2000)][]
         - Starvation at a threshold value of body condition
     - Foraging limits:
-        - Functional response based on [Illius & O’Connor (2000)](http://www.jstor.org/stable/3547323)
+        - Functional response based on [Illius & O’Connor (2000)][]
         - General Holling Type II functional response
-    - Net energy in forage: formula used by [Illius & O’Connor (2000)](http://www.jstor.org/stable/3547323)
+    - Net energy in forage: formula used by [Illius & O’Connor (2000)][]
 - Continuous integration (CI) for GitLab.
 - Output in tab-separated text tables.
 - TOML instruction file reader.
 - Demo simulator with simple logistic grass growth.
 
+[Illius & O’Connor (2000)]: <https://doi.org/10.2307/3800911>
+[Taylor et al. (1981)]: <https://doi.org/10.1017/S0003356100040617>
+
 [Unreleased]: https://github.com/wtraylor/modular_megafauna_model/compare/0.6.0...develop
 [0.6.0]: https://github.com/wtraylor/modular_megafauna_model/compare/0.5.5...0.6.0
 [0.5.5]: https://github.com/wtraylor/modular_megafauna_model/compare/0.5.4...0.5.5
@@ -195,9 +217,13 @@ The format is based on [Keep a Changelog][] by Olivier Lacan, and this project a
 [#8]: https://github.com/wtraylor/modular_megafauna_model/issues/8
 [#9]: https://github.com/wtraylor/modular_megafauna_model/issues/9
 [#10]: https://github.com/wtraylor/modular_megafauna_model/issues/10
+[#12]: https://github.com/wtraylor/modular_megafauna_model/issues/12
+[#14]: https://github.com/wtraylor/modular_megafauna_model/issues/14
 [#15]: https://github.com/wtraylor/modular_megafauna_model/issues/15
 [#22]: https://github.com/wtraylor/modular_megafauna_model/issues/22
 [#25]: https://github.com/wtraylor/modular_megafauna_model/issues/25
 [#26]: https://github.com/wtraylor/modular_megafauna_model/issues/26
 [#28]: https://github.com/wtraylor/modular_megafauna_model/issues/28
 [#29]: https://github.com/wtraylor/modular_megafauna_model/issues/29
+[#31]: https://github.com/wtraylor/modular_megafauna_model/issues/31
+[#32]: https://github.com/wtraylor/modular_megafauna_model/issues/32

CITATION.cff

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2020 W. Traylor <[email protected]>
+#
+# SPDX-License-Identifier: CC0-1.0
+
+cff-version: 1.1.0
+message: If you use this software, please cite it as below.
+authors:
+  - family-names: Traylor
+    given-names: Wolfgang
+    affiliation: Senckenberg Biodiversity and Climate Research Centre
+    orcid: https://orcid.org/0000-0003-4925-7248
+title: "Modular Megafauna Model"
+version: 1.0.0
+# This DOI represents all versions, and will always resolve to the latest one.
+doi: 10.5281/zenodo.4710254
+date-released: 2021-04-26
+license: LGPL-3.0-or-later
+repository-code: https://github.com/wtraylor/modular_megafauna_model

CMakeLists.txt

@@ -1,10 +1,12 @@
-# SPDX-FileCopyrightText: 2020 Wolfgang Traylor <[email protected]>
+# SPDX-FileCopyrightText: 2020 W. Traylor <[email protected]>
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
 cmake_minimum_required (VERSION 3.10)
 project ("Modular Megafauna Model"
-  VERSION 0.5.1
+  # This version must match exactly the Git tag!
+  # Compare the "check_version" job in ".gitlab-ci.yml".
+  VERSION 1.0.0
   DESCRIPTION "A physiological, dynamic herbivore simulator in C++."
   LANGUAGES CXX
   )

CONTRIBUTING.md

@@ -42,14 +42,29 @@ This document is only about *syntax* only.
 - If you are new to Git branching, check out this tutorial: [Learn Git Branching](https://learngitbranching.js.org/)
 
 ### Release Versioning
-- This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-- Each merge into the `master` branch is a release and should have a Git tag.
-    - The tag’s name is just the exact version, e.g. “0.1.2”.
-    - The tag’s decription should summarize the introduced changes.
-- Before merging into `master`:
-    - Set the new version in `CMakeLists.txt`.
-    - List your changes in `CHANGELOG.md`, following the formatting guidelines there.
-- If you cite this code in a journal publication, consider getting a DOI for the specific model version you used.
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html):
+
+- The pattern is `MAJOR.MINOR.PATCH`.
+- If the new version cannot read old instruction files anymore or breaks the library interface, increment `MAJOR`.
+- If the new version introduces a new feature, but still interoperates like the old version, increment `MINOR`.
+- If the new version only fixes bugs, extends or amends the documentation or refactors code, increment `PATCH`.
+
+#### CHECKLIST for merging into `master`:
+
+Each merge into the `master` branch is a release and should have a Git tag.
+
+1. List your changes in `CHANGELOG.md`, following the formatting guidelines there. Rename the “Unreleased” section to the to-be-released version in `CHANGELOG.md`.
+2. Set the new version in `CMakeLists.txt` under `VERSION`.
+3. Set the version and the `date-released:` field in `CITATION.cff`. The date format is `YYYY-MM-DD`.
+4. Now do the merge: `git switch master && git merge --no-ff develop`
+5. Create a new release on GitHub, which will trigger [Zenodo](https://zenodo.org) to archive the code and mint a DOI.
+    - The release and the tag description should summarize the changes (which you can copy-paste from `CHANGELOG.md`.
+    - The name of the tag and the release is just the exact version, e.g. `0.1.2`.
+6. Rebase the `develop` branch: `git switch develop && git rebase master`
+7. Your first commit in `develop` resets everything so that it cannot be confused with a released version:
+    - Set `VERSION 0.0.0` in `CMakeLists.txt`.
+    - Set `version: 0.0.0` in `CITATION.cff`, and empty the `date-released:` field.
+    - Prepare the `[Unreleased]` section in `CHANGELOG.md`.
 
 ### Commit Messages
 Follow Chris Beams’ guide for crafting your Git commit messages: [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)

README.md

@@ -6,6 +6,8 @@ SPDX-License-Identifier: CC-BY-4.0
 
 [![LGPL logo](docs/images/lgpl.svg)](https://choosealicense.com/licenses/lgpl-3.0/)
 [![REUSE-compliant](docs/images/reuse-compliant.svg)][REUSE]
+[![Documentation Status](https://readthedocs.org/projects/modular-megafauna-model/badge/?version=latest)](https://modular-megafauna-model.readthedocs.io/en/latest/?badge=latest)
+[![DOI](https://zenodo.org/badge/228426088.svg)](https://zenodo.org/badge/latestdoi/228426088)
 
 [REUSE]: https://reuse.software
 
@@ -28,6 +30,8 @@ Since this C++ library is Free Software, the scientific community is encouraged
 
 Come join the MMM user and developer room on Matrix: <https://matrix.to/#/!rnevkLtJTORmvyzFHD:matrix.org?via=matrix.org>
 
+Project documentation: <https://modular-megafauna-model.readthedocs.io/>
+
 Repository Structure
 --------------------
 
@@ -49,11 +53,11 @@ Usage
 The first step in working with the model is to create the documentation and read the introductory pages.
 On the Quickstart page you will find instructions for compiling the source code.
 
-The compiled documentation of the latest release is currently available for download as a ZIP file from Open Science Framework [here](https://osf.io/jzn5a/download).
-As soon as this repository is public, the documentation will be available on [Read the Docs](http://readthedocs.io/) (issue [#22](https://github.com/wtraylor/modular_megafauna_model/issues/22)).
-
 ### Compile the Doxygen Documentation
 
+You can find the automatically compiled documentation of the latest release here:
+<https://modular-megafauna-model.readthedocs.io/>
+
 As a bare minimum, you will need to have [CMake](https://cmake.org) (version 3.10 or higher) and [Doxygen](https://www.doxygen.nl) installed.
 
 Open a Unix shell (terminal) in the root directory of the megafauna library, and execute the following lines.
@@ -78,6 +82,7 @@ Now open the created file `docs/index.html` in a web browser.
 
 Originally this megafauna model was developed for the dynamic global vegetation model [LPJ-GUESS](http://iis4.nateko.lu.se/lpj-guess/).
 On the Lund subversion server there exists a branch `megafauna` that integrates this library into LPJ-GUESS.
+LPJ-GUESS is proprietary and closed-source.
 Please contact the maintainers of LPJ-GUESS to kindly ask for access.
 
 Other dynamic vegetation models can include the megafauna model as an external library, too.
@@ -90,6 +95,22 @@ Hopefully you will find it possible to implement the necessary code changes/exte
 You will need basic skills with Git and C++ (C++11 standard) in order to contribute.
 
 On the index/main page of the Doxygen documentation you will be directed to the resources you need to contribute.
+Please also read through the file [`CONTRIBUTING.md`][].
+
+After contributing something, don’t forget to add your name to:
+
+- the file header in a new line starting with `SPDX-FileCopyrightText: ...` (following the [REUSE][] standard),
+- the “[Authors][#authors]” section in this README, and
+- the list of authors in the citation file [`CITATION.cff`][].
+
+(Note that the authors list in the [Zenodo archive][] is automatically derived from the contributors in the Git history.)
+
+[Zenodo archive]: <https://zenodo.org/badge/latestdoi/228426088>
+
+Continuous Integration (CI) runs through gitlab.com in this mirror repository: <https://gitlab.com/wtraylor/modular_megafauna_model>
+
+Note that for running the model, you don’t need to change the source code.
+Most parameters can be set in the instruction file.
 
 Known Bugs and Issues
 ---------------------
@@ -102,14 +123,18 @@ Compare [Understanding the GitHub flow](https://guides.github.com/introduction/f
 Authors
 -------
 
-- Wolfgang Traylor ([email protected]) ![ORCID][orcid-logo] <https://orcid.org/0000-0002-4813-1072>
+- Wolfgang Traylor ([email protected]) ![ORCID][orcid-logo] <https://orcid.org/0000-0002-4813-1072>, Senckenberg Biodiversity and Climate Research Centre ([SBiK-F][])
 
-[orcid-logo]: https://orcid.org/sites/default/files/images/orcid_16x16.gif
+[orcid-logo]: <https://info.orcid.org/wp-content/uploads/2020/12/ORCIDiD_icon16x16.png>
+[SBiK-F]: <https://www.senckenberg.de/en/institutes/sbik-f/>
 
 Similar Projects
 ----------------
 
-<!--TODO: Provide a list of references to other mechanistic herbivore models.-->
+- Dangal, Shree R. S., Hanqin Tian, Chaoqun Lu, Wei Ren, Shufen Pan, Jia Yang, Nicola Di Cosmo, and Amy Hessl. 2017. “Integrating Herbivore Population Dynamics into a Global Land Biosphere Model: Plugging Animals into the Earth System.” Journal of Advances in Modeling Earth Systems 9 (8): 2920–45. <https://doi.org/10.1002/2016MS000904>.
+- Illius, A. W., and T. G. O’Connor. 2000. “Resource Heterogeneity and Ungulate Population Dynamics.” Oikos 89 (2): 283–94. <https://doi.org/10.1034/j.1600-0706.2000.890209.x>.
+- Pachzelt, Adrian, Anja Rammig, Steven Higgins, and Thomas Hickler. 2013. “Coupling a Physiological Grazer Population Model with a Generalized Model for Vegetation Dynamics.” Ecological Modelling 263: 92–102. <https://doi.org/http://dx.doi.org/10.1016/j.ecolmodel.2013.04.025>.
+- Zhu, Dan, Philippe Ciais, Jinfeng Chang, Gerhard Krinner, Shushi Peng, Nicolas Viovy, Josep Peñuelas, and Sergey Zimov. 2018. “The Large Mean Body Size of Mammalian Herbivores Explains the Productivity Paradox During the Last Glacial Maximum.” Nature Ecology & Evolution. <https://doi.org/10.1038/s41559-018-0481-y>.
 
 License
 -------

docs/CMakeLists.txt

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2020 Wolfgang Traylor <[email protected]>
+# SPDX-FileCopyrightText: 2020 W. Traylor <[email protected]>
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later