uttrflow / uttrflow/uttrflow-swift
CONTRIBUTING.md doesn't mention the stale-build test failures that swift package clean fixes
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 3h 32m
- Merged PRs (30d)
- 277
Description
## What happens
After pulling a change that adds a case to a public enum in one module, an incremental build can keep stale objects for the modules that use it. Tests then fail in ways that cannot be true, such as an expectation printing `nil == nil` as a failure. `swift package clean` followed by `make verify` fixes it.
`CONTRIBUTING.md` has no troubleshooting section, and nothing in it or in `AGENTS.md` mentions this.
## Why it matters
A first-time contributor who hits it will reasonably think they broke something, or that `main` is broken.
## How to check
Search `CONTRIBUTING.md` for "clean" or "troubleshooting". There is no match.
## Acceptance criteria
- `CONTRIBUTING.md` gains a short "If the build or tests misbehave" section (a few lines, in the file's existing voice) with:
- the symptom: impossible test failures such as `nil == nil` after pulling, typically after an enum gained a case;
- the fix: `swift package clean`, then `make verify`;
- a reminder to `export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer` first, since the wrong toolchain gives confusing errors too.
- `make verify` passes (the docs and link checks run on Markdown).
## Where to start
- `CONTRIBUTING.md` (after "How a change gets in" is a natural place)
- Tests to extend: none; `make verify` checks the Markdown.
- Before pushing, run `make verify` (export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer first). It is the same command CI runs, and it enforces the 95% coverage floor per module.
- Read [CONTRIBUTING.md](https://github.com/uttrflow/uttrflow-swift/blob/main/CONTRIBUTING.md) first, and say on this issue that you are taking it.
**Size:** XS, under an hour.
Contributor guide
Research direction
Read CONTRIBUTING.md, placing the new troubleshooting section after “How a change gets in” to match the existing voice. Document the stale-build symptom, export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer, then run swift package clean and make verify. Done means the guidance and commands are included and make verify passes, including Markdown checks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 92/100