[WIP, DON'T MERGE] Update automatic versioning

.github/changelog_template.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+{{changelog}}

.github/get-changelog-diff.sh

@@ -0,0 +1,4 @@
+git remote add upstream https://github.com/PSLmodels/OG-Core.git
+git fetch --tags upstream
+last_tagged_commit=`git describe --tags --abbrev=0 --first-parent`
+git --no-pager diff $last_tagged_commit -- CHANGELOG.md

.github/has-functional-changes.sh

@@ -0,0 +1,12 @@
+#! /usr/bin/env bash
+
+IGNORE_DIFF_ON="README.md CONTRIBUTING.md Makefile .gitignore LICENSE* .github/* environment.yml"
+
+last_tagged_commit=$(git describe --tags --abbrev=0 --first-parent) # --first-parent ensures we don't follow tags not published in master through an unlikely intermediary merge commit
+
+if git diff-index --name-only --exit-code $last_tagged_commit -- . $(echo " $IGNORE_DIFF_ON" | sed 's/ / :(exclude)/g'); then # Check if any file that has not be listed in IGNORE_DIFF_ON has changed since the last tag was published.
+  echo "No functional changes detected."
+  exit 1
+else
+  echo "The functional files above were changed."
+fi

.github/is-version-number-acceptable.sh

@@ -0,0 +1,33 @@
+#! /usr/bin/env bash
+
+if [[ ${GITHUB_REF#refs/heads/} == master ]]
+then
+    echo "No need for a version check on master."
+    exit 0
+fi
+
+if ! $(dirname "$BASH_SOURCE")/has-functional-changes.sh
+then
+    echo "No need for a version update."
+    exit 0
+fi
+
+current_version=`python setup.py --version`
+
+if git rev-parse --verify --quiet $current_version
+then
+    echo "Version $current_version already exists in commit:"
+    git --no-pager log -1 $current_version
+    echo
+    echo "Update the version number in setup.py before merging this branch into master."
+    echo "Look at the changelog_entry.yaml documentation file to learn how the version number should be updated."
+    exit 1
+fi
+
+if ! $(dirname "$BASH_SOURCE")/has-functional-changes.sh | grep --quiet CHANGELOG.md
+then
+    echo "CHANGELOG.md has not been modified, while functional changes were made."
+    echo "Explain what you changed before merging this branch into master."
+    echo "Look at the contributor_guide.md documentation file to learn how to write the changelog_entry.yaml."
+    exit 2
+fi

.github/publish-git-tag.sh

@@ -0,0 +1,4 @@
+#! /usr/bin/env bash
+
+git tag -a v`python setup.py --version`
+git push --tags || true  # update the repository version

.github/workflows/build_and_test.yml

@@ -21,6 +21,25 @@ on:
       - '**.pkl'
       - '**.pbz2'
 jobs:
+  check-version:
+    name: Check version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Build changelog
+        run: pip install yaml-changelog>=0.1.7 && make changelog
+      - name: Preview changelog update
+        run: ".github/get-changelog-diff.sh"
+      - name: Check version number has been properly updated
+        run: .github/is-version-number-acceptable.sh
   build:
     runs-on: ${{ matrix.os }}
     strategy:

.github/workflows/check_black.yml → .github/workflows/check_format.yml

@@ -1,15 +1,15 @@
 
-name: Check Black formatting
+name: Check code formatting
 
 on: [push, pull_request]
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
       - uses: psf/black@stable
         with:
           options: "-l 79 --check"
-          src: "."
+          src: "."

.github/workflows/publish_to_pypi.yml

@@ -1,13 +1,42 @@
-name: Publish package to PyPI
+name: Tag, release, and publish package to PyPI
 
 on:
   push:
     branches:
       - master
 
 jobs:
+  versioning:
+    name: Update versioning
+    if: |
+      (github.repository == 'PSLmodels/OG-Core')
+      && !(github.event.head_commit.message == 'Update OG-Core')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+          token: ${{ secrets.OGCORE_GITHUB }}
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Build changelog
+        run: pip install yaml-changelog && make changelog
+      - name: Preview changelog update
+        run: ".github/get-changelog-diff.sh"
+      - name: Update changelog
+        uses: EndBug/add-and-commit@v9
+        with:
+          add: "."
+          committer_name: Github Actions[bot]
+          author_name: Github Actions[bot]
+          message: Update OG-Core
+          github_token: ${{ secrets.OGCORE_GITHUB }}
   deploy:
-    name: Publish to PyPI
+    name: Tag, release, Publish to PyPI
     if: github.repository == 'PSLmodels/OG-Core'
     runs-on: ubuntu-latest
     steps:
@@ -17,6 +46,15 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+      - name: Publish new git tag
+        run: ".github/publish-tag.sh || true"
+      - name: Publish new release
+        uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          body: |
+            ${{ steps.preview.outputs.changelog }}
+          name: ${{ github.ref[1:] }}
       - name: Build package
         run: make pip-package
       - name: Publish a Python distribution to PyPI

Makefile

@@ -5,6 +5,18 @@
 #              to work in that environment (and not on Windows).
 # USAGE: OG-Core$ make [TARGET]
 
+changelog:
+	build-changelog changelog.yaml --output changelog.yaml --update-last-date --start-from 0.11.9 --append-file changelog_entry.yaml
+	build-changelog changelog.yaml --org PSLmodels --repo OG-Core --output CHANGELOG.md --template .github/changelog_template.md
+	bump-version changelog.yaml setup.py
+	rm changelog_entry.yaml || true
+	touch changelog_entry.yaml
+format:
+	black . -l 79
+	linecheck . --fix
+documentation:
+	jb clean ./docs/book
+	jb build ./docs/book
 .PHONY=help
 help:
 	@echo "USAGE: make [TARGET]"

README.md

@@ -3,8 +3,8 @@
 | | |
 | --- | --- |
 | Org | [![PSL cataloged](https://img.shields.io/badge/PSL-cataloged-a0a0a0.svg)](https://www.PSLmodels.org) [![OS License: CCO-1.0](https://img.shields.io/badge/OS%20License-CCO%201.0-yellow)](https://github.com/PSLmodels/OG-Core/blob/master/LICENSE) [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://pslmodels.github.io/OG-Core/) |
-| Package | [![Python 3.9](https://img.shields.io/badge/python-3.9-blue.svg)](https://www.python.org/downloads/release/python-3916/) [![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3108/) [![Python 3.11](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3118/) [![PyPI Latest Release](https://img.shields.io/pypi/v/ogcore.svg)](https://pypi.org/project/ogcore/) [![PyPI Downloads](https://img.shields.io/pypi/dm/ogcore.svg?label=PyPI%20downloads)](https://pypi.org/project/ogcore/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) |
-| Testing | ![example event parameter](https://github.com/PSLmodels/OG-Core/actions/workflows/build_and_test.yml/badge.svg?branch=master) ![example event parameter](https://github.com/PSLmodels/OG-Core/actions/workflows/deploy_docs.yml/badge.svg?branch=master) ![example event parameter](https://github.com/PSLmodels/OG-Core/actions/workflows/check_black.yml/badge.svg?branch=master) [![Codecov](https://codecov.io/gh/PSLmodels/OG-Core/branch/master/graph/badge.svg)](https://codecov.io/gh/PSLmodels/OG-Core) |
+| Package | [![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3108/) [![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3118/) [![PyPI Latest Release](https://img.shields.io/pypi/v/ogcore.svg)](https://pypi.org/project/ogcore/) [![PyPI Downloads](https://img.shields.io/pypi/dm/ogcore.svg?label=PyPI%20downloads)](https://pypi.org/project/ogcore/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) |
+| Testing | ![example event parameter](https://github.com/PSLmodels/OG-Core/actions/workflows/build_and_test.yml/badge.svg?branch=master) ![example event parameter](https://github.com/PSLmodels/OG-Core/actions/workflows/deploy_docs.yml/badge.svg?branch=master) ![example event parameter](https://github.com/PSLmodels/OG-Core/actions/workflows/check_format.yml/badge.svg?branch=master) [![Codecov](https://codecov.io/gh/PSLmodels/OG-Core/branch/master/graph/badge.svg)](https://codecov.io/gh/PSLmodels/OG-Core) |
 
 
 OG-Core is an overlapping-generations (OG) model core theory, logic, and solution method algorithms that allow for dynamic general equilibrium analysis of fiscal policy. OG-Core provides a general framework and is a dependency of several country-specific OG models, such as [OG-USA](https://github.com/PSLmodels/OG-USA) and [OG-UK](https://github.com/PSLmodels/OG-UK). The model output includes changes in macroeconomic aggregates (GDP, investment, consumption), wages, interest rates, and the stream of tax revenues over time. Regularly updated documentation of the model theory--its output, and solution method--and the Python API is available [here](https://pslmodels.github.io/OG-Core).
@@ -15,9 +15,9 @@ OG-Core is an overlapping-generations (OG) model core theory, logic, and solutio
 The model is constantly under development, and model components could change significantly. The package will have released versions, which will be checked against existing code prior to release. Stay tuned for an upcoming release!
 
 
-## Using/contributing to OG-Core
+## Using OG-Core
 
-There are two primary methods for installing and running OG-Core on your computer locally. The first and simplest method is to download the most recent `ogcore` Python package from the Python Package Index ([PyPI.org]()). A second option is to fork and clone the most recent version of OG-Core from its GitHub repository and create the conda environment for the `ogcore` package. We detail both of these methods below.
+There are two primary methods for installing and running OG-Core on your computer locally. The first and simplest method is to download the most recent `ogcore` Python package from the Python Package Index ([PyPI.org](https://pypi.org/)). A second option is to fork and clone the most recent version of OG-Core from its GitHub repository and create the conda environment for the `ogcore` package. We detail both of these methods below.
 
 
 ### Installing and Running OG-Core from Python Package Index (PyPI.org)
@@ -84,12 +84,17 @@ If you run into errors running the example script, please open a new issue in th
 The CSV output file `./run_examples/ogcore_example_output.csv` can be compared to the `./run_examples/expected_ogcore_example_output.csv` file that is checked into the repository to confirm that you are generating the expected output. The easiest way to do this is to use the `sh example-diffs` command (or `example-diffs` on Windows) from the `run_examples` directory. If you run into errors running the example script, please open a new issue in the OG-Core repo with a description of the issue and any relevant tracebacks you receive.
 
 
+## Contributing to OG-Core
+
+Instructions for how to submit changes to the OG-Core repository can be found in the "[Contributor Guide](https://pslmodels.github.io/OG-Core/content/contributing/contributor_guide.html)" chapter in the online Jupyter Book documentation (https://pslmodels.github.io/OG-Core/content/contributing/contributor_guide.html). This open source project follows a standard fork/branch/pull request workflow described here (https://guides.github.com/introduction/flow/), and we use semantic versioning 2.0.0 (http://semver.org/). Please follow the approach described in the [Contributor Guide](https://pslmodels.github.io/OG-Core/content/contributing/contributor_guide.html) to submit changes to the model.
+
+
 ## Core Maintainers
 
 The core maintainers of the OG-Core repository are:
 
 * [Jason DeBacker](https://www.jasondebacker.com/) (GitHub handle: [jdebacker](https://github.com/jdebacker)), Associate Professor, Department of Economics, Darla Moore School of Business, University of South Carolina; President, PSL Foundation; Vice President of Research and Co-founder, Open Research Group, Inc.
-* [Richard W. Evans](https://sites.google.com/site/rickecon/) (GitHub handle: [rickecon](https://github.com/rickecon)), Advisory Board Visiting Fellow, Center for Public Finance, Baker Institute for Public Policy at Rice University; President, Open Research Group, Inc.; Director, Open Source Economics Laboratory
+* [Richard W. Evans](https://sites.google.com/site/rickecon/) (GitHub handle: [rickecon](https://github.com/rickecon)), Senior Economist, Abundance Institute; President, Open Research Group, Inc.; Director, Open Source Economics Laboratory
 
 
 ## Citing OG-Core

changelog.yaml

@@ -0,0 +1,7 @@
+- changes:
+    added:
+    - The first release of the OG-Core model was version 0.7.0 on 2021-08-30 (see CHANGELOG.md)
+    - Many releases were tagged between 2021-08-30 and 2024-06-12 (see CHANGELOG.md)
+    - The most recent release is 0.11.9 (see CHANGELOG.md)
+  date: 2024-06-12 01:00:00
+  version: 0.11.9

changelog_entry.yaml

@@ -0,0 +1,12 @@
+- bump: patch
+  changes:
+    added:
+      - Adds the following files for automatic versioning, `.github/changelog_template.md`, `.github/get-changelog-diff.sh`, `.github/has-functional-changes.sh`, `.github/is-version-number-acceptable.sh`
+      - Adds "Check version" job to `build_and_test.yml` GH Action.
+      - Adds `tag_version.yml` GH Action on push to master branch.
+      - Adds three new functions to `Makefile`
+      - Adds starting `changelog.yaml`.
+      - Updates `contributor_guide.md`.
+      - Updates `README.md`.
+      - Renamed code formatting GH Action from `check_black.yml` to `check_format.yml` and updated the actions within.
+      - Removes hard reference to version number in `./ogcore/__init__.py` so that the version reference automatically updates.