Branches and pull requests
How a task reaches your base branch, by direct commit or one branch and pull request per task, how merges are detected, and what failed and blocked mean.
Publish modes
What Publish does on a task depends on the project's repository and its Publish mode setting, which an Admin or Owner sets in Settings > Git.
One branch per task
A task keeps the branch of its first pull request for its whole life: spec/<project key>/t-<n>-<slug>, such as spec/shop/t-4-reserve-stock. A task with a tracker key carries it in front, as in spec/shop/KAN-43-t-4-reserve-stock.
- Recorded before the first push. Renaming the task does not move its branch.
- Reused by every attempt. Retry, Publish again and a publish after the agreement changed all update the same branch, and reuse the pull request while it is open.
- Never taken over. A first attempt never takes over a branch that already exists.
The pull request is titled spec: T-4 <name>. A task with a tracker key titles it KAN-43 spec: T-4 <name>, and the body links the task and lists the decisions of its answered questions.
Detecting the merge
SpecsGraph asks GitHub or GitLab about every pull request waiting to merge every five minutes, each on its own, so one provider error never stops the others. Check now on the task asks at once. The merge lands the task from the tree the merge produced, so the files that landed are exactly what Git has.
Note
Artefacts are held while a pull request waits
Another task that scopes one of the same artefacts cannot publish until the pull request merges or closes.
States and what to do
Tasks and publishing covers the task's own states, from Draft to Done.
Blocked reasons
- Files changed in the repository (external edit). A file SpecsGraph would overwrite was changed in Git, and the message names the files. An Admin can choose Overwrite, which takes Git's current files as known and publishes again over them. The overwrite is recorded.
- No access. SpecsGraph cannot write to the repository. Fix the connection, as described in Connect GitHub or GitLab.
- Render collision. Two artefacts would write one file. Rename one of them.
- Main moved. Main changed since the publish was planned. Publish again.
An archived project also blocks publishing. Troubleshooting lists other problems and their fixes.
Abandoning a task
Abandon closes the task's open pull request and, shortly after, deletes its branch. A pull request merged before the close still lands, so Git and Main never disagree.
Next steps
- Tasks and publishing: how a task moves from Draft to Done.
- Spec files in your repository: the files and the commit a publish writes.