terraingenpy 0.1.1.dev25__tar.gz → 0.1.1.dev73__tar.gz

terraingenpy-0.1.1.dev73/.github/workflows/ci.yml

@@ -0,0 +1,513 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # The version's pre-release suffix: .devN on main (N commits since the last release tag), none on
+  # release tags (which must match CMakeLists.txt) or pull requests.
+  version:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      suffix: ${{ steps.version.outputs.suffix }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - id: version
+        run: |
+          project=$(sed -nE 's/^set\(TERRAINGEN_FULL_VERSION "([0-9]+\.[0-9]+\.[0-9]+)"\)$/\1/p' CMakeLists.txt)
+          suffix=""
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            if [[ "${GITHUB_REF_NAME#v}" != "$project" ]]; then
+              echo "::error::Tag $GITHUB_REF_NAME does not match CMakeLists.txt's version $project"
+              exit 1
+            fi
+          elif [[ "$GITHUB_EVENT_NAME" == push && "$GITHUB_REF" == refs/heads/main ]]; then
+            if last=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null); then
+              suffix=".dev$(git rev-list --count "$last..HEAD")"
+            else
+              suffix=".dev$(git rev-list --count HEAD)"
+            fi
+          fi
+          {
+            echo "version=$project$suffix"
+            echo "suffix=$suffix"
+          } >> "$GITHUB_OUTPUT"
+          echo "Version $project$suffix"
+
+  lint:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+      - run: python -m pip install pre-commit
+      - run: pre-commit run --all-files --show-diff-on-failure
+      - name: Lint workflows
+        run: docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:1.7.12 -color
+
+  # Build and every test, with the GPU tests on Mesa's lavapipe, the software Vulkan driver, which
+  # TerrainGen uses only when TERRAINGEN_DEVICE names it. The runners have no NVIDIA GPU, so the
+  # CUDA kernels are compiled to PTX but not run.
+  test:
+    name: test (${{ matrix.name }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # The oldest supported Ubuntu, compiler and Python.
+          - { name: ubuntu-22.04-gcc-11, os: ubuntu-22.04, cc: gcc-11, cxx: g++-11, python: "3.10" }
+          - { name: ubuntu-22.04-arm-gcc-11, os: ubuntu-22.04-arm, cc: gcc-11, cxx: g++-11 }
+          - { name: ubuntu-24.04-clang-18, os: ubuntu-24.04, cc: clang-18, cxx: clang++-18 }
+          - { name: macos-14, os: macos-14 }
+          - { name: windows-2022-msvc, os: windows-2022 }
+    env:
+      CC: ${{ matrix.cc }}
+      CXX: ${{ matrix.cxx }}
+      CCACHE_DIR: ${{ github.workspace }}/.ccache
+      TERRAINGEN_DEVICE: "0"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python || '3.12' }}
+      - run: python -m pip install numpy pytest ninja
+      # MSVC on the path for the Ninja generator.
+      - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
+        if: runner.os == 'Windows'
+      - uses: hendrikmuhs/ccache-action@f09c25b45002a07be2955cbe52e8cee55643f89d # v1.2.24
+        if: runner.os != 'Windows'
+        with:
+          key: ${{ matrix.name }}
+          max-size: 500M
+      - name: Install lavapipe
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends mesa-vulkan-drivers libvulkan1
+          icd=$(find /usr/share/vulkan/icd.d -name 'lvp_icd*.json' | head -n1)
+          echo "VK_DRIVER_FILES=$icd" >> "$GITHUB_ENV"
+          echo "VK_ICD_FILENAMES=$icd" >> "$GITHUB_ENV"
+      - name: Install lavapipe
+        if: runner.os == 'Windows'
+        shell: bash
+        run: .github/scripts/install-lavapipe-windows.sh
+      - name: Install lavapipe
+        if: runner.os == 'macOS'
+        run: |
+          brew install mesa vulkan-loader
+          prefix=$(brew --prefix)
+          icd=$(find "$prefix/share/vulkan/icd.d" -name 'lvp_icd*.json' | head -n1)
+          {
+            echo "VK_DRIVER_FILES=$icd"
+            echo "VK_ICD_FILENAMES=$icd"
+            echo "DYLD_FALLBACK_LIBRARY_PATH=$prefix/lib"
+          } >> "$GITHUB_ENV"
+      - name: Configure
+        shell: bash
+        run: >
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DTERRAINGEN_BUILD_BENCHMARKS=OFF
+          "-DPython_EXECUTABLE=$(python -c 'import sys; print(sys.executable)')"
+          ${{ runner.os != 'Windows' && '-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache' || '' }}
+      - name: Build
+        run: cmake --build build --parallel 4
+      - name: Backends
+        shell: bash
+        run: build/bin/terraingen backends
+      - name: Test
+        run: ctest --test-dir build --parallel 4 --output-on-failure --timeout 1200
+
+  # Line coverage of the library, from the tests on lavapipe; GitHub Pages publishes the report from
+  # main (pages job).
+  coverage:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    env:
+      CCACHE_DIR: ${{ github.workspace }}/.ccache
+      TERRAINGEN_DEVICE: "0"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install gcovr numpy pytest ninja
+      - uses: hendrikmuhs/ccache-action@f09c25b45002a07be2955cbe52e8cee55643f89d # v1.2.24
+        with:
+          key: coverage
+          max-size: 1G
+      - name: Install lavapipe
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends mesa-vulkan-drivers libvulkan1
+      - name: Configure
+        run: >
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DTERRAINGEN_COVERAGE=ON
+          -DTERRAINGEN_BUILD_BENCHMARKS=OFF
+          "-DPython_EXECUTABLE=$(python -c 'import sys; print(sys.executable)')"
+          -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
+      # Everything first: the coverage target builds only the test programs, not the command and
+      # examples that the integration tests run.
+      - name: Build
+        run: cmake --build build --parallel 4
+      # The tests four at a time (ctest reads CTEST_PARALLEL_LEVEL), the long examples first.
+      - name: Test and report
+        env:
+          CTEST_PARALLEL_LEVEL: "4"
+        run: cmake --build build --target coverage
+      - name: Summary
+        if: always()
+        run: cat build/coverage/summary.md >> "$GITHUB_STEP_SUMMARY" || true
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: coverage-report
+          path: build/coverage/
+          if-no-files-found: ignore
+          retention-days: 7
+
+  # One job per platform and Python (pyproject.toml's [tool.cibuildwheel] has the rest), so each
+  # platform's wheels build side by side.
+  wheel:
+    name: wheel (${{ matrix.os }}, ${{ matrix.python }})
+    needs: version
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm, macos-15-intel, macos-14, windows-2022]
+        python: [cp310, cp311, cp312]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Version
+        shell: bash
+        run: >
+          sed -i.bak -E 's/^set\(TERRAINGEN_FULL_VERSION "([0-9.]+)"\)$/set(TERRAINGEN_FULL_VERSION "\1${{ needs.version.outputs.suffix }}")/'
+          CMakeLists.txt
+      - uses: pypa/cibuildwheel@b3395e271a35f73dad77f21802abe9b986dfe299 # v4.3.1
+        env:
+          CIBW_BUILD: "${{ matrix.python }}-*"
+        with:
+          output-dir: wheelhouse
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: wheel-${{ matrix.os }}-${{ matrix.python }}
+          path: wheelhouse/*.whl
+
+  # The sdist, then a wheel built from it and imported, as pip does for platforms without wheels.
+  sdist:
+    needs: version
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Version
+        run: >
+          sed -i -E 's/^set\(TERRAINGEN_FULL_VERSION "([0-9.]+)"\)$/set(TERRAINGEN_FULL_VERSION "\1${{ needs.version.outputs.suffix }}")/'
+          CMakeLists.txt
+      - run: python -m pip install build
+      - run: python -m build --sdist
+      - name: Install from the sdist
+        run: |
+          python -m pip install dist/*.tar.gz
+          cd "$RUNNER_TEMP" && python -c "import terraingen; print(terraingen.__version__)" && terraingen backends
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # The documentation, built against the Linux wheel, for every push and pull request; another
+  # platform's wheel failing does not skip it.
+  docs:
+    needs: wheel
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: wheel-ubuntu-24.04-cp312
+          path: wheel
+      - name: Install Doxygen, TerrainGen and the docs requirements
+        run: |
+          sudo apt-get update && sudo apt-get install -y --no-install-recommends doxygen
+          python -m pip install wheel/*.whl -r docs/requirements.txt
+      - name: Build
+        run: make -C docs build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: site
+          path: site
+          retention-days: 3
+
+  # The documentation with the coverage report under coverage/ (and coverage/badge.json for the
+  # README badge), on GitHub Pages from main. A failed coverage run leaves the report out.
+  pages:
+    needs: [docs, coverage]
+    if: ${{ !cancelled() && needs.docs.result == 'success' && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: site
+          path: site
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        continue-on-error: true
+        with:
+          name: coverage-report
+          path: site/coverage
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+
+  # The CLI, library, headers and CMake package for each platform as an archive, and Debian packages
+  # (terraingen, terraingen-dev) built on the oldest supported Ubuntu.
+  packages:
+    name: packages (${{ matrix.platform }})
+    needs: version
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { platform: linux-x86_64, os: ubuntu-22.04 }
+          - { platform: linux-aarch64, os: ubuntu-22.04-arm }
+          - { platform: macos-arm64, os: macos-14 }
+          - { platform: macos-x86_64, os: macos-15-intel }
+          - { platform: windows-x86_64, os: windows-2022 }
+    env:
+      ARCHIVE: terraingen-${{ needs.version.outputs.version }}-${{ matrix.platform }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install ninja
+      - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
+        if: runner.os == 'Windows'
+      - name: Version
+        shell: bash
+        run: >
+          sed -i.bak -E 's/^set\(TERRAINGEN_FULL_VERSION "([0-9.]+)"\)$/set(TERRAINGEN_FULL_VERSION "\1${{ needs.version.outputs.suffix }}")/'
+          CMakeLists.txt
+      - name: Build
+        shell: bash
+        run: |
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DTERRAINGEN_BUILD_TESTS=OFF \
+            -DTERRAINGEN_BUILD_BENCHMARKS=OFF -DTERRAINGEN_BUILD_EXAMPLES=OFF \
+            -DTERRAINGEN_BUILD_PYTHON=OFF -DTERRAINGEN_INSTALL=ON
+          cmake --build build --parallel 4
+          cmake --install build --prefix "$ARCHIVE"
+          cp LICENSE README.md CHANGELOG.md "$ARCHIVE/"
+      - name: Archive
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: Compress-Archive -Path "$env:ARCHIVE" -DestinationPath "$env:ARCHIVE.zip"
+      - name: Archive
+        if: runner.os != 'Windows'
+        run: tar -czf "$ARCHIVE.tar.gz" "$ARCHIVE"
+      - name: Debian packages
+        if: runner.os == 'Linux'
+        run: cpack --config build/CPackConfig.cmake -G DEB -B debs
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: packages-${{ matrix.platform }}
+          path: |
+            ${{ env.ARCHIVE }}.zip
+            ${{ env.ARCHIVE }}.tar.gz
+            debs/*.deb
+          if-no-files-found: error
+
+  # The Debian packages installed on clean distributions, where the program must run and list its
+  # backends. Only the Linux packages matter here, so another platform's failure does not skip it; a
+  # missing Linux package fails its download.
+  package-test:
+    name: package-test (${{ matrix.image }}, ${{ matrix.arch }})
+    needs: packages
+    if: ${{ !cancelled() }}
+    runs-on: ${{ matrix.arch == 'aarch64' && 'ubuntu-24.04-arm' || 'ubuntu-24.04' }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [x86_64, aarch64]
+        image: ["ubuntu:22.04", "ubuntu:24.04", "debian:12"]
+    container: ${{ matrix.image }}
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: packages-linux-${{ matrix.arch }}
+      - name: Install
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends ./debs/*.deb
+      - name: Run
+        run: |
+          terraingen --version
+          terraingen backends
+
+  # The Dockerfile's image, built and tested on the oldest supported Ubuntu; pushed to GHCR from main
+  # (dev) and release tags.
+  docker:
+    needs: [version, lint, test]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Build
+        run: docker build --target dev -t terraingen:test .
+      - name: Smoke test
+        run: |
+          docker run --rm terraingen:test terraingen --version
+          docker run --rm terraingen:test terraingen backends
+          docker run --rm terraingen:test python -c "import terraingen; print(terraingen.__version__)"
+      - name: Push
+        if: github.event_name == 'push'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          image=ghcr.io/${GITHUB_REPOSITORY,,}
+          echo "$GH_TOKEN" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            version=${GITHUB_REF_NAME#v}
+            tags=("$version" "${version%.*}" latest)
+          else
+            tags=(dev)
+          fi
+          for tag in "${tags[@]}"; do
+            docker tag terraingen:test "$image:$tag"
+            docker push "$image:$tag"
+          done
+
+  # Wheels and the sdist to PyPI by Trusted Publishing (no stored token): X.Y.Z.devN from main,
+  # X.Y.Z from release tags, once every platform's build, tests and packages pass.
+  pypi:
+    needs: [lint, test, wheel, sdist, package-test]
+    if: >
+      github.event_name == 'push' &&
+      (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/terraingenpy/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: wheel-*
+          merge-multiple: true
+          path: dist
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: sdist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  # The "latest" pre-release: main's packages and their checksums, replaced on every push to main.
+  # Marked as a pre-release and never as the latest release, so versioned releases stay the default.
+  latest:
+    needs: [lint, test, packages, package-test]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: "packages-*"
+          merge-multiple: true
+          path: assets
+      - name: Flatten
+        run: find assets -mindepth 2 -type f -exec mv -t assets {} + && find assets -mindepth 1 -type d -empty -delete
+      - name: Checksums
+        run: cd assets && sha256sum -- * > SHA256SUMS
+      - name: Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release delete latest --repo "$GITHUB_REPOSITORY" --cleanup-tag --yes || true
+          gh release create latest assets/* --repo "$GITHUB_REPOSITORY" --target "$GITHUB_SHA" \
+            --prerelease --latest=false --title "Latest (main)" \
+            --notes "Built from main at $GITHUB_SHA. For versioned binaries, use a tagged release."
+
+  # A GitHub release for each v* tag, with every wheel, the sdist, the packages and their checksums.
+  release:
+    needs: [lint, test, wheel, sdist, package-test, docker]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: "wheel-*"
+          merge-multiple: true
+          path: assets
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: sdist
+          path: assets
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: "packages-*"
+          merge-multiple: true
+          path: assets
+      - name: Flatten
+        run: find assets -mindepth 2 -type f -exec mv -t assets {} + && find assets -mindepth 1 -type d -empty -delete
+      - name: Checksums
+        run: cd assets && sha256sum -- * > SHA256SUMS
+      - name: Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: >
+          gh release create "$GITHUB_REF_NAME" assets/*
+          --repo "$GITHUB_REPOSITORY" --title "TerrainGen ${GITHUB_REF_NAME#v}" --generate-notes

terraingenpy-0.1.1.dev73/CHANGELOG.md

@@ -0,0 +1,83 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Piecewise uniform size-frequency distributions: counts per diameter band, given absolutely or as shares of a total.
+- Radial wall marks on craters, ridges and grooves down the wall that are strongest where it is steepest.
+- Thomas cluster process for boulder clusters, with Poisson-scattered centres whose clusters add where they overlap.
+- Craters on slopes: floors offset downslope and rims and ejecta lowered upslope (Plescia et al. 2019), and faster wear toward a critical gradient (Roering et al. 1999).
+- Boulders limited to a maximum slope, optionally rolling down steeper ground to gather at its foot.
+- Density maps from GeoTIFFs or constants: a scale, a count in a diameter range, or an areal fraction such as rock abundance, which set crater and boulder densities point by point.
+- Size slope maps that bend boulder sizes into a local power law, from an exponent or a mean diameter map.
+- Crater and boulder catalogs with a completeness limit, above which they stand in for generated features.
+- Configuration reference in the documentation, generated from the schema at build time, and machine-readable value ranges in the schema.
+- Rock albedo: boulders brighter than the regolith (Holt 1981; Marshal et al. 2023), and a speckle of the share of each sample covered by boulders too small to resolve, with the scatter of randomly placed rocks.
+- Slope albedo: steep ground kept immature by mass wasting, its optical maturity rising with slope beyond 20 degrees (Ikeda et al. 2022; Lucey et al. 2014).
+- Crater shaping and datum fitting on the GPU on spheres, ellipsoids and shape models, not only on planes.
+- Configurations are checked against every field's documented range, and errors name the exact field, such as `layers[2].reach`.
+- Python options classes document every field with its description and unit, and gain `validate()` and a readable `repr`.
+
+### Changed
+
+- Defaults give a plausible lunar terrain at 1 m per pixel in which every height layer shows: craters from a production surface capped below the Trask equilibrium with steady-state ages, diffusion and irregular outlines; Surveyor boulders; noise relief scaled to its wavelength; and visible roughness, bedforms and dunes.
+- Boulder lists and models hold every boulder of the layer's diameter range; only the heightmap leaves out boulders too small to resolve.
+- Boulder ejecta come from every crater layer before the boulder layer, not only the last one.
+- The boulder layer's `exposure_spacing` key is now `ground_spacing` (Python `ground_spacing`), the spacing of every ground read the layer makes.
+- Crater shaping has one implementation, the kernel, on every surface; craters on bodies and custom profiles may differ from before in the last digits.
+- Random streams and hashes are unified, so boulder, albedo, dune, bedform and pavement outputs for a given seed differ from earlier versions; their statistics are unchanged.
+- Every evaluation defaults to all threads, including `EvaluateAt`, `EvaluateTile` and Python `evaluate_tile`.
+- The `materials` module is folded into `pipeline` (material maps) and `albedo` (Hapke photometry); include `terraingen/pipeline/materials.h` and `terraingen/albedo/photometry.h`.
+- Python: `ExposureField.exposure` takes `(x, y, spacing=0.0, terrain=None, layers=0)` like the other ground queries, unbounded options read as `None` instead of infinity, `write_outputs` returns paths, a subclass missing a required method raises `TypeError`, and `CraterFeatures.write` is `write_list`.
+- Python names: `cell_of` is `cell_at`, `point_of` is `coordinates`, `level_for` is `resolving_level`, `outline_of` is `irregular_outline`, `min_diameter_for_count` is `count_limit_diameter`, `singer_range_for_size` is `singer_max_range`, `SplotchOptions` is `SplotchAlbedoOptions` and `SlopeMaturityOptions` is `SlopeAlbedoOptions`.
+- The CI coverage job builds at `-O1` without atomic counters, so it caches and runs several times faster.
+
+- Density maps that count every feature take out the secondaries thrown from a layer's craters and the blocks thrown out around craters, and boulder patches and bedrock keep a map's mean, so nothing is counted twice.
+- Boulder models settle onto a stable face by default instead of balancing on an edge or corner.
+- Boulder generation logs under boulders rather than craters.
+- Crater and boulder generation summaries log at debug level; `terraingen` ends with one line counting the files written instead of listing each, and feature outputs log how long they took.
+- Generation logs each grid as it is evaluated, with the time of every layer, the albedo and the materials, and ends with each step's total and share.
+- Faster boulders: the ground beneath them is read in one batch, outputs over one region share the boulders placed for the first, models are placed in parallel, ejecta craters are found through a spatial index and shapes skip the roughness of fracture planes that cannot reach a vertex. The hero demo runs in about 10 s instead of 276 s.
+- Martin, Parkes and Dunstan is the default crater profile.
+
+### Fixed
+
+- Freshness degradation never makes a crater deeper than fresh: basins shallower than the cutoff keep their fresh shape.
+- Small craters inside larger ones on sloping ground no longer stand as raised mounds: datums are fitted to the slope-shaped relief that is applied.
+- Crater layers over other layers read the ground beneath their slopes and datums in batches rather than point by point, and point batches are evaluated in spatial order: the hero demo went from 433 s to 11 s with the same output.
+- Secondary craters run on the GPU backend the terrain asks for instead of always on the CPU.
+- A crater layer after a boulder layer no longer refits crater datums for every batch of ground reads.
+- Tilted boulders are no longer cut off at tile edges and point queries.
+- Crater and boulder lists honour a spacing finer than the grid.
+- Zero-area regions and crater sizes below the models' range are rejected with a clear error instead of failing during generation.
+
+### Removed
+
+- Python `crater_blend_weight` (use `CraterBlend.weight`), `CraterAgeModel.lifetime_gyr` (use `lifetime_at`) and the flat selection aliases on crater irregularity, crater albedo and secondary options (use `selection`).
+
+## [0.1.0] - 2026-10-18
+
+Initial release.
+
+### Added
+
+- C++20 library with Python bindings (`terraingenpy` on PyPI) for generating terrain from scratch or adding detail to existing DEMs.
+- Craters and boulders from published size-frequency distributions, with crater ages, profiles, degradation, irregularity, secondaries and ejecta.
+- Procedural 3D boulder models, and small boulders baked into the heightmap.
+- Synthetic albedo with crater ejecta and rays that fade with age.
+- Geologic features: dunes and ripples, layered strata, fractured bedrock, ventifacts and sand pooled in lows or behind boulders.
+- Planes, spheres and ellipsoids, whole-body meshes, tiles and point queries.
+- Deterministic output for a seed on any grid, tile or thread count.
+- GPU acceleration on Vulkan, CUDA and Metal, detected at run time.
+- `terraingen` command-line interface driven by JSON configurations.
+- Examples in C++, Python and JSON.
+- Release archives for Linux, macOS and Windows, Debian packages, and a Docker image.
+
+[Unreleased]: https://github.com/alexmaietta/terraingen/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/alexmaietta/terraingen/releases/tag/v0.1.0