Initial repo setup

.github/ISSUE_TEMPLATE/software_release.md

@@ -0,0 +1,35 @@
+---
+name: spanerr release checklist
+about: Checklist for releasing new versions of spanerr
+title: Release v
+labels: chore
+assignees: ''
+---
+
+## release prep
+
+- [ ] Pull updated copies of the develop and main branches.
+- [ ] Use git-flow to create a new release branch with the appropriate version (e.g., `git flow release start 0.5.0`).
+- [ ] Update release version to appropriate number (set to final version without any pre-release or dev tags).
+- [ ] Create a PR for the release (from release branch to `main`).
+- [ ] Review the changelog to make sure that all features, changes, bugfixes, etc. included in the release are documented. You may want to review the git revision history to be sure you've captured everything.
+- [ ] Confirm that all checks for the PR pass (e.g., unit tests, code coverage checks).
+- [ ] Review code documentation to make sure it is up to date.
+- [ ] Review the commit logs to make sure all logs are meaningful and sufficient. To revise and squash commit messages, use `git rebase -i`.
+- [ ] Request a review for the PR.
+- [ ] Once approved, use git-flow to finish the release (`git flow release finish`).
+  *Make sure to use the `-M`, `--merge-message` flag to customize the commit message for the merge and
+  the `--message` flag to specify the tag message.*
+
+## after release
+
+- With `post-release-update` feature branch (automatically created for you by git-flow hook):
+  - [ ] Increase the develop branch version so it is set to the next expected release (i.e., if you just released 0.5.0 then develop will probably be 0.6.0.dev0 unless you are working on a major update, in which case it will be 1.0.0.dev0).
+  - [ ] Update the changelog to include a section for the next expected release version.
+  - [ ] Create a PR and request a review once all checks are passing.
+- [ ] Push main branch updates to GitHub (`git push main`).
+  *This will fail if the release's PR has not been approved or has failing checks.*
+- [ ] Push tag to GitHub (e.g., `git push origin tag 0.5.0`).
+- [ ] Create release on GitHub.
+- [ ] Merge `post-release-update` to develop.
+  *This will fail if the feature's PR has not been approved or has failing checks.*

.github/workflows/changelog.yml

@@ -0,0 +1,51 @@
+# Inspired by the changelog-check-action (https://github.com/tarides/changelog-check-action)
+
+name: Check Changelog
+on:
+  pull_request:
+    # opened/synchronize/reopened: Check changelog when PR is created or updated
+    # labeled/unlabeled: Re-run check when "no changelog" label is added/removed
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+    branches: [develop, main]
+
+permissions:
+  contents: read
+
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CHANGELOG: CHANGELOG.md
+  BASE_REF: ${{ github.base_ref }}
+  # Has no changelog label
+  HAS_LABEL: ${{ contains(github.event.pull_request.labels.*.name, 'no changelog') }}
+
+jobs:
+  check-changelog:
+    name: Verify Changelog Updated
+    runs-on: ubuntu-latest
+    # For labeled/unlabeled actions, only run if it involves the "no changelog" label
+    if: >
+      (contains(github.event.action, 'label') && github.event.label.name == 'no changelog')
+      || ! contains(github.event.action, 'label')
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Check changelog
+        run: |
+          if ${HAS_LABEL}; then
+            echo "Check passes, since 'no changelog' label is set"
+            exit 0
+          elif git diff --exit-code "origin/${BASE_REF}" -- "${CHANGELOG}"; then
+            echo "Error: User-visible changes should come with an entry in the changelog."
+            echo "For changes not user-visible, add the 'no changelog' label to override this behavior."
+            exit 1
+          else
+            echo "Check passes, changes detected in ${CHANGELOG}"
+          fi

.github/workflows/pr-check.yml

@@ -0,0 +1,50 @@
+name: Check GitHub Pull Request
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+
+permissions: {}
+
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate-gitflow:
+    name: Validate GitFlow branch rules
+    runs-on: ubuntu-latest
+    env:
+      HEAD_REF: ${{ github.head_ref }}
+    steps:
+      - name: Check PRs to main
+        if: github.base_ref == 'main'
+        run: |
+          if [[ "$HEAD_REF" =~ ^(release|hotfix)/ ]]; then
+            echo "PASS: PRs from release and hotfix branches can target main"
+            exit 0
+          elif [[ ${HEAD_REF} =~ ^dependabot/ ]]; then
+            echo "ERROR: Cannot directly merge Dependabot updates"
+            echo "Add desired updates to a release, hotfix, or feature branch"
+            exit 1
+          else
+            echo "ERROR: PRs targeting main must come from a release or hotfix branch"
+            exit 1
+          fi
+
+      - name: Check PRs to develop
+        if: github.base_ref == 'develop'
+        run: |
+          if [[ "$HEAD_REF" = "main" || "$HEAD_REF" =~ ^feature/ ]]; then
+            echo "PASS: PRs from main and feature branches can target develop"
+            exit 0
+          elif [[ "$HEAD_REF" =~ ^dependabot/ ]]; then
+            echo "PASS: PRs from Dependabot updates can target develop"
+            exit 0
+          else
+            echo "ERROR: PRs targeting develop must come from main, Dependabot updates, or a feature branch"
+            exit 1
+          fi

.github/workflows/ruff-checks.yml

@@ -0,0 +1,34 @@
+name: Check Ruff linter + formatter
+on:
+  # Run on pull requests to develop or main
+  pull_request:
+    branches: [develop, main]
+  # Allow running manually
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ruff:
+    name: Run Ruff checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+      - name: Run Ruff linter
+        uses: astral-sh/ruff-action@0ce1b0bf8b818ef400413f810f8a11cdbda0034b  #v4.0.0
+        with:
+          args: "check --output-format=github"
+      - name: Run Ruff formatter
+        # NOTE: ruff format does not currently support github output format
+        run: ruff format --check --diff
+        # Check formatting even if the previous step failed
+        if: always()

.pre-commit-config.yaml

@@ -0,0 +1,74 @@
+# This config file specifies which pre-commit hooks to run.
+#
+# To set up, run `pre-commit install`
+# To run all hooks manually, run `pre-commit run --all-files`
+repos:
+  # Ruff Python linter and formatter (configs in pyproject.toml)
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 0671d8ab202c4ac093b78433ae5baf74f3fc7246  # frozen: v0.15.15
+    hooks:
+      # Run the linter
+      - id: ruff-check
+        args: [--fix, --show-fixes]  # enable lint fixes
+      # Run the formatter
+      - id: ruff-format
+  # mdformat for formatting Markdown files
+  - repo: https://github.com/hukkin/mdformat
+    rev: 2d496dbc18e31b83a1596685347ffe0b6041daf0  # frozen: 1.0.0
+    hooks:
+      - id: mdformat
+        # Optionally add plugins
+        additional_dependencies:
+          - mdformat-pyproject  # support configuration in pyproject.toml
+          - mdformat-frontmatter  # support GitHub front-matter
+  # yamlfmt for formatting YAML files
+  - repo: https://github.com/google/yamlfmt
+    rev: b5ca1890231d5e1e5181fef75a1be609d1e25029  # frozen: v0.21.0
+    hooks:
+      - id: yamlfmt
+  # Codespell for spell checking
+  - repo: https://github.com/codespell-project/codespell
+    rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a  # frozen: v2.4.2
+    hooks:
+      - id: codespell
+        additional_dependencies:
+          - tomli  # For Python 3.10
+  # Some out-of-the-box file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # frozen: v6.0.0
+    hooks:
+      # Check for files with merge conflict strings
+      - id: check-merge-conflict
+      # Verify syntax of TOML files
+      - id: check-toml
+      # Verify syntax of YAML files
+      - id: check-yaml
+        args: [--unsafe]
+      # Verifies that test files begin with test_
+      - id: name-tests-test
+        args: [--pytest-test-first]
+      # Removes trailing whitespace from all files
+      - id: trailing-whitespace
+        exclude: "docs/"
+  # Check uv.lock file is up to date
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    # uv version
+    rev: 3e7518446022606defbcdadcf8170a40cc680a8c  # frozen: 0.11.18
+    hooks:
+      - id: uv-lock
+  # Validate Github Actions schema
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 943377262562a12b57292fc98fabd7dbf81451fe  # frozen: 0.37.2
+    hooks:
+      - id: check-github-workflows
+  # Validate Github Actions workflow files
+  - repo: https://github.com/mpalmer/action-validator
+    rev: 76a805bbfcba3506d6cdb4bba1810ab504e0d72b  # frozen: v0.9.0
+    hooks:
+      - id: action-validator
+  # Security-focused GitHub Actions static analysis tool
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: 9257c6050c0261b8c57e712f632dc4a8010109a9  # frozen: v1.25.2
+    hooks:
+      - id: zizmor
+        args: [--fix=safe]  # enable safe fixes

.python-version

@@ -0,0 +1,2 @@
+# Pinned python version for development (used by uv)
+3.12

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Change & Version Information
+
+## 0.1.0
+
+Initial alpha release.

DEVELOPERNOTES.md

@@ -0,0 +1,116 @@
+# Developer Notes
+
+This project uses git flow branching conventions via [git-flow-next](https://github.com/gittower/git-flow-next).
+
+> [!NOTE]
+> Make sure you are using the correct version of git flow.
+> The original [git-flow](https://github.com/nvie/gitflow) and its successor [git-flow-avh](https://github.com/petervanderdoes/gitflow-avh) are no longer maintained.
+> While `git-flow-next` is backwards compatible, this project assumes the workflow and features of `git-flow-next`.
+
+For development, we assume the usage of [uv](https://docs/astral.sh/uv/).
+`uv` is compatible with the use of `pip` for python package management and a tool
+of your choice for creating python virtual environments (e.g., `mamba`, `venv`).
+
+## Initial setup and installation
+
+### Initialize and configure git-flow in your local repository
+
+Install `git-flow-next` if it's not installed.
+It can be installed via Homebrew or manual installation.
+See `git-flow-next`'s [installation documentation](https://git-flow.sh/docs/installation/) for more details.
+
+To initialize git-flow run:
+
+```sh
+git flow init --preset=classic --defaults
+```
+
+This package uses custom configurations options for git-flow including the use of custom git-flow hooks which are defined in `gitflow-hooks`.
+Run the provided `setup_gitflow.sh` script to update git-flow's configuration.
+
+```sh
+sh setup_gitflow.sh
+```
+
+These configuration options are set in the local git config (`.git/config`).
+
+To display an overview of the current git-flow configuration, branch structure, and workflow status run:
+
+```sh
+git flow overview
+```
+
+### Install uv
+
+Install `uv` if it's not installed.
+It can be installed via PyPi, Homebrew, or a standalone installer.
+See `uv`'s [installation documentation](https://docs.astral.sh/uv/getting-started/installation)
+for more details.
+
+To explicitly sync the project's dependencies, including optional dependencies for
+development and testing, to your local environment run:
+
+```sh
+uv sync
+```
+
+Note that `uv` performs syncing and locking automatically (e.g., any time
+`uv run` is invoked). By default, syncing will remove any packages not
+specifically specified in the `pyproject.toml`.
+
+### Install pre-commit hooks
+
+Anyone who wants to contribute to this codebase should install the configured pre-commit hooks.
+
+To install pre-commit run:
+
+```sh
+uv tool install pre-commit --with pre-commit-uv
+```
+
+To install the configure pre-commit hooks run:
+
+```sh
+pre-commit install
+```
+
+This will configure a pre-commit hooks to automatically lint and format python code with [ruff](https://github.com/astral-sh/ruff) and [black](https://github.com/psf/black).
+
+To run pre-commit explicitly run:
+
+```sh
+pre-commit run --all-files
+```
+
+Pre-commit hooks and formatting conventions were added at version 0.5, so `git blame` may not reflect the true author of a given change. To make `git blame` more accurate, ignore formatting revisions:
+
+```sh
+git blame <FILE> --ignore-revs-file .git-blame-ignore-revs
+```
+
+Or configure your git to always ignore styling revision commits:
+
+```sh
+git config blame.ignoreRevsFile .git-blame-ignore-revs
+```
+
+## Unit testing
+
+Unit tests are set up to be used with [pytest](https://docs.pytest.org/).
+
+To run the tests, run:
+
+```sh
+uv run pytest
+```
+
+## Pull requests
+
+To propose code changes, create a pull request against the **develop** branch
+(per our git flow workflow). Pull requests should include an update to `CHANGELOG.md`
+documenting the changes to the project.
+
+Several GitHub Actions are run for pull requests: unit testing, code coverage,
+ruff checks, and a changelog check. By default, the changelog check will fail if
+the PR does not update `CHANGELOG.md`. For pull requests that do not modify code,
+the "no changelog" label can be added to skip this check.

codecov.yml

@@ -0,0 +1,12 @@
+coverage:
+  status:
+    project:
+      default: false  # disable the default status that measures entire project
+      core:  # custom target for core package
+        target: 90%
+        paths:
+          - "src/spanerr/"
+      tests:  # 100% coverage for test files
+        target: 100%
+        paths:
+          - "tests/"  # only include coverage in tests folder