The working method

This page is how a change gets into Tilde: one issue, one branch, tests first, a review, a pull request into develop. Every change follows these steps.

The branches

• develop is the integration branch. Every change lands here.
• main holds the releases. It only moves when develop is merged into it (see Releases and CI).
• A feature branch lives for one issue and is deleted after the merge.

The steps

1. An issue. I open an issue on Codeberg that says what I want and why. It is written in the first person or in a neutral voice, in English.

2. A branch. A very small change, such as a typo or one line of a script, goes straight on develop. Anything else gets its own branch from develop, in a separate worktree when I have other work open:

   git worktree add ../Tilde-fix-thing -b fix/thing develop

3. Tests first. I write the test that fails, then the code that makes it pass, then I tidy the code with the tests green. A bug fix starts with a test that shows the bug. See Build and test for how to run them.

4. Small commits. Each commit is a Conventional Commit in English (feat(core): ..., fix(cli): ..., docs: ..., test: ...). The title says what changed and the body says why. Releases and the changelog are computed from these messages, so the type matters (see Releases and CI).

5. A review of the whole branch. When the work is done, I read the full diff of the branch against develop as a reviewer would: wrong behavior, missing tests, code that breaks the code convention, claims in the documentation that the code does not support. I fix what is wrong and note what is only a matter of taste.

6. A pull request into develop. The description says what changed, why, and how I tested it. It links the issue.

7. A merge commit. I merge with the merge style (“Create merge commit” on the page of the pull request), so every commit of the branch stays in the history. I do not squash and I do not rebase. From a terminal:

   tea pulls merge <number> --repo squidd/Tilde --style merge

8. Cleaning up. After the merge I delete the branch and the worktree, and I close the issue.

   git worktree remove ../Tilde-fix-thing
   git branch -d fix/thing

What a change keeps

• The code convention. It is strict on purpose, so a review can check it.
• The documentation. A change to a command, a key or a configuration key changes its page in the same pull request. See Write the documentation.
• The licenses. A new package means new third-party notices.
• Plans and design notes stay out of the repository, in docs/plans too: the repository holds the code and its documentation.

Why this way

Tilde is a project I build in my spare time, to learn. One issue and one branch at a time keep each piece small enough to finish. Writing the test first shows me what I want before I write it. The review of the whole branch catches what I miss while I am inside the details. The merge commit keeps the path I took, not only where I arrived.