When asked to "commit and push" changes in this project, follow this process exactly. The release script reads git commit subjects to build the GitHub release changelog, so message format matters.
Before committing, always verify the build is clean:
ARCH_OVERRIDE=arm64 ./scripts/build.sh && \
python3 scripts/audit_mount_calls.py && \
xcodebuild -project macfuseGui.xcodeproj \
-scheme macfuseGui \
-configuration Debug \
-derivedDataPath build/DerivedData \
-destination 'platform=macOS,arch=arm64' \
test CODE_SIGNING_ALLOWED=NOAll tests must pass and the audit must print PASS before you commit.
scripts/release.sh generates release notes by reading git log subjects since the
last vX.Y.Z tag. Each commit subject is transformed and bucketed:
| Prefix in subject | Displayed as | Section |
|---|---|---|
fix: |
Fix: <message> |
### Fixes |
feat: |
New: <message> |
### Other Changes |
perf: |
Performance: <message> |
### Other Changes |
refactor: |
Refactor: <message> |
### Other Changes |
chore: / build: / ci: / style: / test: |
Maintenance: <message> |
### Other Changes |
docs: |
Docs: <message> |
### Other Changes |
| (no prefix) | shown as-is | ### Other Changes |
Commits are excluded from the changelog if every changed file matches:
^docs/ | \.html$ | ^scripts/.*\.sh$ | ^macfuseGuiTests?/ | ^macfuseGuiTest/
(case-insensitive). A commit that touches both a production file and a test file is included because it has at least one non-ignored path.
Release commits (Release vX.Y.Z) are always excluded.
Use conventional commit format. The subject becomes the changelog bullet. The body
explains the why for engineers reading git log.
fix: concise description of what was wrong and what was fixed
Paragraph explaining the root cause and the concrete failure scenario.
Second paragraph if needed for additional context or edge cases.
Co-Authored-By: Claude <Model Name> <noreply@anthropic.com>
Rules:
- Subject line: imperative mood, ≤ 72 characters, no trailing period
- Blank line between subject and body
- Body: explain why the change was needed, not what lines changed
- Always append the
Co-Authored-Bytrailer, naming the model that actually authored the change (e.g.Claude Opus 4.7)
One logical fix or feature per commit. Group all files that belong to the same change together. Do not batch unrelated changes into one commit.
Example groupings from a four-bug session:
Commit 1 macfuseGui/Services/KeychainService.swift
macfuseGuiTests/KeychainServiceTests.swift
Commit 2 macfuseGui/Services/MountStateParser.swift
macfuseGui/Services/UnmountService.swift
Commit 3 macfuseGui/Services/MountCommandBuilder.swift
macfuseGui/Services/MountManager.swift
macfuseGuiTests/MountArgBuilderTests.swift
Commit 4 macfuseGui/ViewModels/RemotesViewModel.swift
When one file contains changes from two different bugs: keep that file in the commit for the more important fix rather than using interactive patch splitting. Note in both commit bodies that the file also carries the other change.
Use explicit git add <file> [file ...] — never git add . or git add -A.
When incorporating external PR work: preserve contributor attribution. If the
final commit substantially uses a contributor's proposed fix, include their
Co-Authored-By trailer or clearly credit them in the commit body and release notes.
Do not use dismissive wording such as "churn" for Xcode-generated .xcstrings or
.pbxproj diffs; Xcode may rewrite those files during normal project use.
git add macfuseGui/Services/KeychainService.swift macfuseGuiTests/KeychainServiceTests.swift
git commit -m "$(cat <<'EOF'
fix: return trimmed password from KeychainService to prevent whitespace auth failures
readPassword returned the raw stored value even after trimming it to check for
blank-only passwords. A password pasted with a trailing newline was returned
with that whitespace intact, causing silent SSH authentication failures.
Co-Authored-By: Claude <Model Name> <noreply@anthropic.com>
EOF
)"Use a HEREDOC for the message to avoid quoting issues with apostrophes or special chars.
After all commits are made:
git push origin mainNo force push. No --no-verify. If the push is rejected, investigate — do not override.
- Bug fixes →
fix:prefix → appears under ### Fixes in the release notes - New behaviour, improvements →
feat:,perf:, or bare subject → ### Other Changes - Test-only changes → use
test:prefix; will be filtered out of the changelog entirely - Internal cleanup with no user-visible effect →
refactor:orchore:
When in doubt about whether something is user-facing, use fix: or feat: so it
appears in the changelog. Changelog readers are end users checking what changed.
- Reliability gate passes (audit + tests)
- Changes grouped into one commit per logical fix/feature
- Each commit uses
fix:or appropriate prefix - Subject line is ≤ 72 chars and describes the user-visible problem, not the code
- Body explains root cause and failure scenario
-
Co-Authored-Bytrailer present -
git addlists explicit files only -
git push origin main— clean, no force