Skip to content

Commit 11b3379

Browse files
brendancolbrendancol
authored
added claude commands associated with project maintenance (#982)
1 parent 3f02572 commit 11b3379

File tree

5 files changed

+548
-0
lines changed

5 files changed

+548
-0
lines changed

‎.claude/commands/new-issues.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# New Issues: Feature Gap Analysis and Issue Creation
2+
3+
Audit the README feature matrix, identify gaps and opportunities, and file
4+
GitHub issues for the best candidates. The prompt is: $ARGUMENTS
5+
6+
---
7+
8+
## Step 1 -- Read the feature matrix
9+
10+
1. Read `README.md` and extract every function listed in the feature matrix tables.
11+
2. For each function, record:
12+
- Category (Surface, Hydrology, Focal, etc.)
13+
- Backend support (which of the four columns are native, fallback, or missing)
14+
3. Read the source files referenced in the matrix to confirm what actually exists
15+
(the README can drift from reality).
16+
17+
## Step 2 -- Identify backend gaps
18+
19+
1. List every function where one or more backends show 🔄 (fallback) or blank
20+
(unsupported).
21+
2. Prioritize gaps where:
22+
- The function already has 3 of 4 backends (low effort to complete the set)
23+
- The missing backend is CuPy or Dask+CuPy (GPU support matters for large rasters)
24+
- The function is commonly used by GIS analysts (slope, aspect, flow direction, etc.)
25+
3. Draft 1-3 maintenance issues for the highest-value backend completions.
26+
27+
## Step 3 -- Identify missing features
28+
29+
Think about what GIS analysts and Python spatial data scientists actually need
30+
that the library does not yet provide. Consider:
31+
32+
- **Surface analysis gaps:** contour line extraction, profile/cross-section tools,
33+
terrain shadow analysis, sky-view factor, landform classification
34+
(Weiss 2001, Jasiewicz & Stepinski 2013)
35+
- **Hydrology gaps:** HAND (Height Above Nearest Drainage) generation (not just
36+
flood-depth-from-HAND), depression filling / breach, channel width estimation,
37+
compound topographic index (CTI / wetness index)
38+
- **Focal / neighborhood gaps:** directional filters, morphological operators
39+
(erode, dilate, open, close), texture metrics (entropy, GLCM), circular
40+
or annular kernels
41+
- **Multispectral gaps:** water indices (NDWI, MNDWI), built-up indices (NDBI),
42+
snow index (NDSI), tasseled cap, PCA, band math DSL
43+
- **Interpolation gaps:** natural neighbor, RBF (radial basis function),
44+
trend surface
45+
- **Zonal gaps:** zonal geometry (area, perimeter, centroid), majority/minority
46+
filter, zonal histogram
47+
- **Network / connectivity:** cost-path corridor, least-cost corridor,
48+
visibility network (intervisibility between multiple points)
49+
- **Time series:** temporal compositing (median, max-NDVI), change detection,
50+
phenology metrics
51+
- **I/O and interop:** raster clipping to polygon, raster merge/mosaic,
52+
coordinate reprojection helpers
53+
54+
Do NOT suggest features that duplicate what GDAL/rasterio already do well
55+
unless there is a clear benefit to having a pure-Python/Numba version (e.g.
56+
GPU support, Dask integration, no C dependency).
57+
58+
Select the 3-5 most impactful feature suggestions. Rank by:
59+
1. How often GIS analysts need the operation (daily-use beats niche)
60+
2. How well it fits the library's existing architecture
61+
3. Whether it fills a gap no other GDAL-free Python library covers
62+
63+
## Step 4 -- Draft the issues
64+
65+
For each candidate (both maintenance and new-feature), draft a GitHub issue
66+
following the `.github/ISSUE_TEMPLATE/feature-proposal.md` template:
67+
68+
- **Title:** short, imperative (e.g. "Add NDWI water index to multispectral module")
69+
- **Labels:** `enhancement` plus any topical labels that fit
70+
- **Body sections:**
71+
- Reason or Problem
72+
- Proposal (Design, Usage, Value)
73+
- Stakeholders and Impacts
74+
- Drawbacks
75+
- Alternatives
76+
- Unresolved Questions
77+
78+
Keep each issue body concise. Cite specific algorithms or papers where
79+
relevant. Include a short code snippet showing the proposed API.
80+
81+
## Step 5 -- Humanize and create
82+
83+
1. Collect all drafted issue bodies into a batch.
84+
2. **Run each issue body through the `/humanizer` skill** to strip AI writing
85+
patterns before creating the issue.
86+
3. Create each issue with `gh issue create`, passing the humanized title,
87+
body, and labels.
88+
4. Record the issue numbers and URLs.
89+
90+
## Step 6 -- Summary
91+
92+
Print a table of all created issues:
93+
94+
```
95+
| # | Title | Labels | URL |
96+
|---|-------|--------|-----|
97+
```
98+
99+
Then briefly explain the rationale: why these issues were chosen, what
100+
analyst workflows they unblock, and any issues you considered but dropped
101+
(with a one-line reason for each).
102+
103+
---
104+
105+
## General rules
106+
107+
- Do not create duplicate issues. Before filing, search existing issues with
108+
`gh issue list --limit 100 --state all` and skip anything already covered.
109+
- Run `/humanizer` on every issue title and body before creating it.
110+
- If $ARGUMENTS contains specific focus areas (e.g. "hydrology only"),
111+
restrict the analysis to those categories.
112+
- If $ARGUMENTS is empty, run the full analysis across all categories.
113+
- Prefer fewer, higher-quality issues over a long wishlist.

‎.claude/commands/release-major.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Release: Major
2+
3+
Cut a major release (X.Y.Z -> X+1.0.0). Follow every step below in order.
4+
5+
$ARGUMENTS
6+
7+
---
8+
9+
## Step 1 -- Determine the new version
10+
11+
1. Run `git tag --sort=-v:refname | head -5` to find the latest tag.
12+
2. Parse the current version (format `vX.Y.Z`).
13+
3. Increment the **major** component and reset minor+patch: `X.Y.Z` -> `(X+1).0.0`.
14+
4. Store the new version string (without `v` prefix) for later steps.
15+
16+
## Step 2 -- Create a release branch
17+
18+
```bash
19+
git checkout master && git pull
20+
git checkout -b release/vX.Y.Z
21+
```
22+
23+
## Step 3 -- Update CHANGELOG.md
24+
25+
1. Run `git log --pretty=format:"- %s" <latest_tag>..HEAD` to collect
26+
changes since the last release.
27+
2. Add a new section at the top of CHANGELOG.md (below the header line)
28+
matching the existing format:
29+
```
30+
### Version X.Y.Z - YYYY-MM-DD
31+
32+
#### New Features
33+
- feature description (#PR)
34+
35+
#### Bug Fixes & Improvements
36+
- fix description (#PR)
37+
```
38+
3. Use today's date. Categorize entries under "New Features" and/or
39+
"Bug Fixes & Improvements" as appropriate.
40+
4. Run `/humanizer` on the changelog text before writing it.
41+
42+
## Step 4 -- Commit and push
43+
44+
```bash
45+
git add CHANGELOG.md
46+
git commit -m "Update CHANGELOG for vX.Y.Z release"
47+
git push -u origin release/vX.Y.Z
48+
```
49+
50+
## Step 5 -- Verify CI
51+
52+
1. Run `gh pr create --title "Release vX.Y.Z" --body "Changelog update for vX.Y.Z major release."` to open a PR against master.
53+
2. Wait for CI:
54+
```bash
55+
gh pr checks <PR_NUMBER> --watch
56+
```
57+
3. If CI fails, fix the issue, amend or add a commit, push, and re-check.
58+
59+
## Step 6 -- Merge the release branch
60+
61+
```bash
62+
gh pr merge <PR_NUMBER> --merge --delete-branch
63+
```
64+
65+
## Step 7 -- Tag the release
66+
67+
```bash
68+
git checkout master && git pull
69+
git tag -a vX.Y.Z -m "Version X.Y.Z"
70+
git push origin vX.Y.Z
71+
```
72+
73+
Do **not** sign the tag (`-s` flag omitted).
74+
75+
## Step 8 -- Create a GitHub release
76+
77+
```bash
78+
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <(changelog_excerpt)
79+
```
80+
81+
Use the CHANGELOG section for this version as the release notes body.
82+
Run `/humanizer` on the notes before creating the release.
83+
84+
## Step 9 -- Verify PyPI
85+
86+
1. The `pypi-publish.yml` workflow triggers automatically on tag push.
87+
2. Watch the workflow:
88+
```bash
89+
gh run list --workflow=pypi-publish.yml --limit 1
90+
gh run watch <RUN_ID>
91+
```
92+
3. Confirm the new version appears:
93+
```bash
94+
pip index versions xarray-spatial 2>/dev/null || echo "Check https://pypi.org/project/xarray-spatial/"
95+
```
96+
97+
## Step 10 -- Summary
98+
99+
Print the new version, links to the PR, GitHub release, and PyPI page.
100+
101+
---
102+
103+
## General rules
104+
105+
- Run `/humanizer` on all text destined for GitHub: PR title/body, release
106+
notes, commit messages, and any comments left on issues or PRs.
107+
- Any temporary files created during the release (build artifacts, scratch
108+
files) must use unique names including the version number to avoid
109+
collisions (e.g. `changelog-draft-1.0.0.md`).

‎.claude/commands/release-minor.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Release: Minor
2+
3+
Cut a minor release (X.Y.Z -> X.Y+1.0). Follow every step below in order.
4+
5+
$ARGUMENTS
6+
7+
---
8+
9+
## Step 1 -- Determine the new version
10+
11+
1. Run `git tag --sort=-v:refname | head -5` to find the latest tag.
12+
2. Parse the current version (format `vX.Y.Z`).
13+
3. Increment the **minor** component and reset patch: `X.Y.Z` -> `X.(Y+1).0`.
14+
4. Store the new version string (without `v` prefix) for later steps.
15+
16+
## Step 2 -- Create a release branch
17+
18+
```bash
19+
git checkout master && git pull
20+
git checkout -b release/vX.Y.Z
21+
```
22+
23+
## Step 3 -- Update CHANGELOG.md
24+
25+
1. Run `git log --pretty=format:"- %s" <latest_tag>..HEAD` to collect
26+
changes since the last release.
27+
2. Add a new section at the top of CHANGELOG.md (below the header line)
28+
matching the existing format:
29+
```
30+
### Version X.Y.Z - YYYY-MM-DD
31+
32+
#### New Features
33+
- feature description (#PR)
34+
35+
#### Bug Fixes & Improvements
36+
- fix description (#PR)
37+
```
38+
3. Use today's date. Categorize entries under "New Features" and/or
39+
"Bug Fixes & Improvements" as appropriate.
40+
4. Run `/humanizer` on the changelog text before writing it.
41+
42+
## Step 4 -- Commit and push
43+
44+
```bash
45+
git add CHANGELOG.md
46+
git commit -m "Update CHANGELOG for vX.Y.Z release"
47+
git push -u origin release/vX.Y.Z
48+
```
49+
50+
## Step 5 -- Verify CI
51+
52+
1. Run `gh pr create --title "Release vX.Y.Z" --body "Changelog update for vX.Y.Z minor release."` to open a PR against master.
53+
2. Wait for CI:
54+
```bash
55+
gh pr checks <PR_NUMBER> --watch
56+
```
57+
3. If CI fails, fix the issue, amend or add a commit, push, and re-check.
58+
59+
## Step 6 -- Merge the release branch
60+
61+
```bash
62+
gh pr merge <PR_NUMBER> --merge --delete-branch
63+
```
64+
65+
## Step 7 -- Tag the release
66+
67+
```bash
68+
git checkout master && git pull
69+
git tag -a vX.Y.Z -m "Version X.Y.Z"
70+
git push origin vX.Y.Z
71+
```
72+
73+
Do **not** sign the tag (`-s` flag omitted).
74+
75+
## Step 8 -- Create a GitHub release
76+
77+
```bash
78+
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <(changelog_excerpt)
79+
```
80+
81+
Use the CHANGELOG section for this version as the release notes body.
82+
Run `/humanizer` on the notes before creating the release.
83+
84+
## Step 9 -- Verify PyPI
85+
86+
1. The `pypi-publish.yml` workflow triggers automatically on tag push.
87+
2. Watch the workflow:
88+
```bash
89+
gh run list --workflow=pypi-publish.yml --limit 1
90+
gh run watch <RUN_ID>
91+
```
92+
3. Confirm the new version appears:
93+
```bash
94+
pip index versions xarray-spatial 2>/dev/null || echo "Check https://pypi.org/project/xarray-spatial/"
95+
```
96+
97+
## Step 10 -- Summary
98+
99+
Print the new version, links to the PR, GitHub release, and PyPI page.
100+
101+
---
102+
103+
## General rules
104+
105+
- Run `/humanizer` on all text destined for GitHub: PR title/body, release
106+
notes, commit messages, and any comments left on issues or PRs.
107+
- Any temporary files created during the release (build artifacts, scratch
108+
files) must use unique names including the version number to avoid
109+
collisions (e.g. `changelog-draft-0.9.0.md`).

0 commit comments

Comments
 (0)