Skip to content

docs: replace raw HTTP examples with supported clients #348

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mikemcdougall merged 1 commit into from
Aug 13, 2026
+29 −27
Merged

docs: replace raw HTTP examples with supported clients #348

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,13 @@ jobs:
fetch-depth: 0
persist-credentials: false

- name: Enforce maintained documentation command policy
run: |
if git grep -n -i -w curl -- '*.md' '*.mdx' '*.rst' '*.txt'; then
Comment on lines +46 to +47

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Limit the policy check to maintained documentation

Restrict this scan to actual documentation paths and command examples. Git's git grep -h states that -i performs case-insensitive matching and -w matches at word boundaries, while these unrestricted globs include non-documentation artifacts such as tests/Honua.Migrate.Maui.Tests/Fixtures/*.cs.txt; consequently, an unrelated fixture or explanatory paragraph containing the word “curl” will fail the entire changes job even when it provides no raw HTTP workflow.

Useful? React with 👍 / 👎.

echo "::error::Maintained documentation must use supported SDK, CLI, or API-reference workflows."
exit 1
fi

- name: Check for source changes
id: filter
env:
Expand Down
16 changes: 11 additions & 5 deletions docs/getting-started/tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,14 +263,20 @@ dotnet build -t:Run -f net10.0-windows10.0.19041.0 # Windows
### Verify Sync

```bash
# Check your server dashboard at:
# https://api.honua.io/dashboard
# Install the supported Honua command-line client once.
npm install --global @honua/sdk-js

# Or query via API:
curl -H "X-API-Key: your-api-key" \
"https://api.honua.io/rest/services/mobile_offline_demo/FeatureServer/68910/query?where=1%3D1&outFields=*&f=json"
# Point it at your deployment and use the same API key as the app.
export HONUA_BASE_URL=https://api.honua.io
export HONUA_API_KEY=your-api-key

# Verify that synchronized records are queryable.
honua query mobile_offline_demo/68910 --where "1=1" --limit 25 --format geojson
```

You can also inspect the synchronized layer in the server dashboard at
<https://api.honua.io/dashboard>.

## Compare to Competition

This table is a planning comparison for the template and SDK surface, not a
Expand Down
17 changes: 7 additions & 10 deletions docs/guides/migration-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,16 +54,13 @@ Fulcrum is a popular field data collection platform charging $99-299/month per u

#### 1. **Export Your Fulcrum Data** (30 minutes)

```bash
# Using Fulcrum API to export your data
curl -H "X-ApiToken: YOUR_FULCRUM_TOKEN" \
"https://api.fulcrumapp.com/api/v2/forms.json" \
> fulcrum_forms.json

curl -H "X-ApiToken: YOUR_FULCRUM_TOKEN" \
"https://api.fulcrumapp.com/api/v2/records.json" \
> fulcrum_records.json
```
Use Fulcrum's supported export workflow to download the form definition and
records as `fulcrum_forms.json` and `fulcrum_records.json`. Keep attachments in
the export directory so the later import can preserve their relative paths.
Comment on lines +57 to +59

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Do not promise unsupported attachment preservation

Remove this preservation claim or document a real attachment-import step. A repository-wide search finds no Fulcrum importer consuming these files, and the later sample only submits feature edits while translating photos into URL-shaped values; therefore, when a Fulcrum export contains attachment files, keeping them beside the JSON does not cause the illustrated migration to upload or preserve them and can leave users believing their media was migrated.

Useful? React with 👍 / 👎.


`honua-migrate` does not currently claim a Fulcrum source adapter. Do not send
Fulcrum tokens through hand-written raw HTTP commands; use Fulcrum's product
export or an approved Fulcrum SDK until that adapter is available.

#### 2. **Create Honua App** (5 minutes)

Expand Down
16 changes: 4 additions & 12 deletions tests/conformance/UPSTREAM.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,23 +40,15 @@ deterministic and a fixture set unambiguously corresponds to one
1. **Fetch (CI / local).** `tests/conformance/fetch-fixtures.sh --version
<X.Y.Z> [--dest DIR]` downloads the release asset
`conformance-fixtures-<version>.tar.gz` (+ `.sha256`) from the `v<version>`
GitHub Release of `honua-io/geospatial-grpc` (via `gh release download` when
available, else `curl`/`wget`), verifies the tarball SHA-256, extracts it,
GitHub Release of `honua-io/geospatial-grpc` (preferring the authenticated
GitHub CLI and using the helper's portable fallback otherwise), verifies the tarball SHA-256, extracts it,
re-verifies every file against the in-tarball `SHA256SUMS`, and asserts the
embedded `VERSION` equals the requested pin. It leaves `fixtures/`
(+ `manifest.txt`), `golden/`, `run.sh`, and `VERSION` in `--dest`
(default `./conformance-fixtures-<version>/`).

Equivalent raw pull (no helper):

```bash
v=0.1.0-alpha.1
base="https://github.com/honua-io/geospatial-grpc/releases/download/v${v}"
curl -fsSLO "${base}/conformance-fixtures-${v}.tar.gz"
curl -fsSLO "${base}/conformance-fixtures-${v}.tar.gz.sha256"
sha256sum -c "conformance-fixtures-${v}.tar.gz.sha256"
tar -xzf "conformance-fixtures-${v}.tar.gz"
```
Use the helper rather than reconstructing the release download by hand; it
verifies both the release checksum and the manifest inside the archive.

2. **Locate (tests).** `LiveHonuaServerInteractionTests` discovers the fetched
fixture directory via the `HONUA_MOBILE_CONFORMANCE_FIXTURES_DIR` environment
Expand Down
Loading