Rebase
DevelopmentrebaseRebase is an Agent Skill for development published in the openmeterio/openmeter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Rebase an OpenMeter branch onto another branch and handle repo-specific gotchas like sequential migrations, atlas.sum conflicts, Ent regeneration, and targeted verification.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/openmeterio/openmeter/blob/HEAD/.agents/skills/rebase/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rebase, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Rebase Gotchas
Use this skill when rebasing an OpenMeter branch, especially onto origin/main, and there may be migration, Ent, or generated-code conflicts.
Before rebasing
- Check
git status --short --branchfirst. - Do not start a rebase on top of unrelated uncommitted work without preserving it first.
- Fetch the target branch explicitly before rebasing.
Standard flow
git fetch origin maingit rebase origin/main- Resolve conflicts one commit at a time.
- Prefer
GIT_EDITOR=true git rebase --continuein non-interactive shells.
First rule for conflicts
When a rebase conflict appears, the first move should usually be regenerating generated artifacts:
make generate
Treat this as the default first step before manually resolving conflicted generated files.
Why:
- conflicts often come from generated Ent code
- conflicts can come from API-generated code
- migration-related schema changes often need fresh generated output too
In practice, regenerating first resolves or clarifies most conflicts much faster than hand-merging generated files.
Migration conflicts
OpenMeter migrations must stay sequential by timestamp.
If a rebased commit introduces a migration that is now older than migrations already on the target branch:
- Remove the older migration pair instead of keeping both.
- Do not hand-edit the SQL to force it in.
- Recreate the migration at the new head after regeneration.
Typical flow:
- Remove the outdated
.up.sqland.down.sqlfiles. - Regenerate code:
make generate
- Generate a fresh migration at the current head:
atlas migrate --env local diff <migration-name>
- Stage the newly generated migration pair and
tools/migrate/migrations/atlas.sum.
atlas.sum conflicts
If tools/migrate/migrations/atlas.sum conflicts or gets out of sync:
atlas migrate --env local hash
Then stage atlas.sum. Do not hand-edit checksum entries unless there is no other option.
Ent and generated code
openmeter/ent/schema/*.gois the source of truth.- Never hand-edit
openmeter/ent/db/. - After schema-related rebased changes, run
make generatebefore regenerating migrations. - If generated files conflict, prefer regeneration over manual merge edits when possible.
Shell/runtime notes
- If the ambient shell is missing Go/toolchain binaries, use:
nix develop --impure .#ci -c <command>
-
Prefer direct command execution. Do not wrap commands in
sh -lc,bash -lc, or similar helper shells when a direct invocation works. For environment variables, preferenv KEY=value <command>orKEY=value <command>. -
Atlas migration diffing uses the local dev environment and may require the direnv shell:
direnv exec . atlas migrate --env local diff <migration-name>
Verification
Before continuing or finishing the rebase, run the smallest relevant test slice for the touched area.
For ledger work, the usual check is:
POSTGRES_HOST=127.0.0.1 go test -tags=dynamic ./openmeter/ledger/...
If there is a known pre-existing failure, call it out explicitly and separate it from any new regression introduced by the rebase.
Important reminders
- Never manually rewrite generated migration SQL unless the user explicitly wants that.
- Never keep two migrations that represent the same schema change at different timestamps.
- Prefer regenerating over “merging” generated artifacts.
- Stage only the resolved files for the current rebase step before
git rebase --continue.