mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-16 05:17:24 +01:00
Add guides for landing a fix in someone else's repo and running human playtests (GST-2757) (#4380)
* Add guides for landing a fix in someone else's repo and running human playtests (GST-2757) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Use plain paths in the guides' changelog entry Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
1 parent
eb0aa51c17
commit
984a268306
3 files changed
+107
No files matched your search
@@ -0,0 +1 @@
|
||||
- **Two new short guides.** `docs/howto-land-a-fix-in-someone-elses-repo.md` covers reading the other project's rules, searching for the same fix first, running every guard their CI runs before you open, keeping the change small, and answering each review point in a new commit with the proof rerun. `docs/howto-run-human-playtests.md` covers asking about moments and where people would stop, and why a back-to-back pick between two builds measures the order they were played in, not the builds.
|
||||
@@ -0,0 +1,53 @@
|
||||
# How to land a fix in someone else's repository
|
||||
|
||||
You found a bug in a project you don't own, and you (or your agent) have a fix. Whether it
|
||||
lands depends on the maintainers' rules, their CI and their reviewers, not on yours. This
|
||||
guide is the order we work in: before you design, before you open the pull request, and
|
||||
after each review.
|
||||
|
||||
## Before you design
|
||||
|
||||
1. **Read their rules.** Start with the root `AGENTS.md` or `CLAUDE.md`, then
|
||||
`CONTRIBUTING.md` and the pull request template. Reviewers, people and bots alike, turn
|
||||
those rules into findings, so a rule you skipped becomes a review round.
|
||||
2. **Search for the same fix first.** Look at their main branch, open pull requests,
|
||||
recently merged ones and issues for your symptom, and do it again right before any
|
||||
public step, because a busy main moves daily. If someone is already fixing it, help
|
||||
that fix with a test or a repro instead of opening a second one. A closed issue can
|
||||
still be broken in a new way: link it ("Related: #N") and describe the new error.
|
||||
3. **Read the history of the code you're changing.** `git log -p <file>` shows what the
|
||||
owner chose on purpose. Reuse the mechanism the code already has before adding a new
|
||||
one.
|
||||
4. **Keep it small.** A short fix in the place the owner already maintains beats a large
|
||||
rewrite that also fixes the bug. When a maintainer's smaller fix lands instead of
|
||||
yours, that's a good outcome: close yours and say thanks.
|
||||
|
||||
## Before you open the pull request
|
||||
|
||||
1. **Run every guard their CI runs, on your final commit.** List them from
|
||||
`.github/workflows/`, the `scripts` in `package.json`, a `Makefile` or whatever their
|
||||
CI calls: lint, format, typecheck, size or line-count ratchets, boundary checks, and the
|
||||
tests near your change. A guard you never ran is the easiest way to fail a first
|
||||
review. Your own local review tools don't replace these; they miss repo-specific rules.
|
||||
2. **Prove the fix.** Add one or two tests that fail on their main and pass with your
|
||||
change, and say so in the description with the commands you ran.
|
||||
3. **Follow their format.** Title style, description sections, "Allow edits by
|
||||
maintainers" turned on. Don't edit their changelog, @-mention people or add trailers
|
||||
unless their rules ask for it.
|
||||
|
||||
## After each review
|
||||
|
||||
1. **Sort the failing checks.** For each one, decide whether your change caused it or it
|
||||
already fails on their main, and prove "already fails" by running it on main. Never
|
||||
call a failure pre-existing without that run.
|
||||
2. **Answer each review point in a new commit** on the same branch, so reviewers can see
|
||||
exactly what changed. Don't force-push unless their rules ask for a squash.
|
||||
3. **Rerun the proof on the new head:** the fail-then-pass test and the CI guards from
|
||||
above. Evidence from the previous commit doesn't count.
|
||||
4. **Update the description** so its evidence describes the current head. Reviewers read
|
||||
the description, not the whole thread.
|
||||
5. **Reply once per round,** after the push: map each point to the commit that fixes it,
|
||||
or explain with a file and line why the point doesn't apply.
|
||||
|
||||
These steps come from landing fixes in one outside project so far. Treat them as a
|
||||
starting checklist and expect them to change as they meet more repositories.
|
||||
@@ -0,0 +1,53 @@
|
||||
# How to run a human playtest
|
||||
|
||||
Models can't tell you whether a game is fun or whether a new person gets your app's first
|
||||
screen. People can, but what they tell you depends on what you ask and on the order they
|
||||
see things in. This note covers games, and it works the same for any product flow you
|
||||
want a stranger to try.
|
||||
|
||||
## Ask about moments, not opinions
|
||||
|
||||
"It was boring" can't be fixed. "At minute 4 I had money and nothing to spend it on"
|
||||
points straight at the thing to change. So set up each session to collect moments:
|
||||
|
||||
- **Before they start,** ask three short questions: what device and browser they're on,
|
||||
how often they play or use things like this, and one they've enjoyed lately.
|
||||
- **While they play,** ask them to think out loud: what they're trying to do, what
|
||||
confuses them, when they're bored. When they reach the point where they'd normally
|
||||
stop, they say "I'd stop here" and keep going until the time is up, unless they're
|
||||
stuck. Record the screen and their voice if they agree to it.
|
||||
- **Afterwards,** open questions first, then specific ones:
|
||||
1. In one sentence, what is this and what were you trying to do?
|
||||
2. Your best moment and your worst moment: about when, and what happened?
|
||||
3. Where were you confused or stuck?
|
||||
4. Did your choices matter? Was anything at stake?
|
||||
5. Anything broken, hard to tap, hard to read or hard to scroll? Give the minute.
|
||||
6. If you could change one thing first, what would it be?
|
||||
7. Would you come back to it tomorrow? Yes, maybe or no.
|
||||
|
||||
If you pay testers, reward specific, timestamped moments and bugs someone can reproduce,
|
||||
not long answers.
|
||||
|
||||
## Never pick a winner by playing two builds back to back
|
||||
|
||||
Don't have each tester play build A, then build B, and ask which one they'd keep. The
|
||||
order decides the answer: in the tests this note comes from, the build played second won
|
||||
most of the picks, whichever build it was. Whether testers finished a session also
|
||||
depended on which build they saw first.
|
||||
|
||||
Give each tester one build. Compare builds across testers by where people said "I'd stop
|
||||
here" and by the moments they reported. If one person must try both, randomize the order
|
||||
and still decide from quit points and moments, never from the pick.
|
||||
|
||||
## Turning what they said into fixes
|
||||
|
||||
1. Pull the timestamped moments out of each session: where they'd quit, what confused
|
||||
them, what delighted them, what broke.
|
||||
2. Tag each complaint by area: the opening and how it teaches, controls, readability,
|
||||
balance, stakes, pacing, bugs.
|
||||
3. Count across testers. One tester's gripe is a note; the same gripe from three testers
|
||||
is a fix.
|
||||
4. Rank the list. Each item gets its clips or quotes and a proposed change, and a change
|
||||
still has to show it helps before it ships.
|
||||
|
||||
This note rests on one team's playtests so far. Expect it to change as more teams use it.
|
||||
Reference in new issue
Block a user