uttrflow / uttrflow/uttrflow-swift

CONTRIBUTING.md doesn't mention the stale-build test failures that swift package clean fixes

Open Beginner friendly
#507 0 comments 0 reactions 0 assignees View on GitHub
area:docs area:general documentation good first issue P2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.