Projects
A project is how your board is divided up. The rule that makes it predictable is short: a session belongs to one project, through its repository, and nothing you report is ever refused or dropped for want of a project.
What a project is
A project is one or more repositories with the Linear projects and Jira projects linked to them, saved per organisation. TeamFlow itself is one project of three repositories.
The switcher in the header flips every board to one project, and a project's sources decide what its trackers import.
One project per session, by repository
A session connects to exactly one project, and it is decided by the repository you are working in.
The plugin never names a project and never stamps one on a report. A report carries the repository, and the dashboard works out at read time which project that repository belongs to. Two things follow, and both of them are useful:
- Moving a repository from one project to another re-homes its whole history without rewriting a single report.
- A project you create today shows work that was done before it existed.
Two rules keep it unambiguous.
A repository belongs to at most one project per organisation
Adding a repository to a second project is refused, and the refusal names the project that already owns it. In the setup dialog that repository shows the owning project's name instead of a tick box.
If you want it somewhere else, remove it from the first project and add it to the second.
The project in the header is a view
Choosing a project changes what you are looking at. It never changes what a plugin reports, and it never changes where a report is written. You cannot put work in the wrong project by having the wrong one selected.
Work outside a project
Everything that does not fit one of the two rules above is an outside state. The rule for all of them is the same:
Nothing the plugin reports is ever refused, dropped or deleted for want of a project.
The repository is in no project
The report lands as usual and the work shows under Outside any project, with an option to add it to one beside it.
teamflow status and teamflow doctor both say so, and a session is told once when it starts. This is the state worth catching: work is arriving and no project view is showing it.
To fix it, add the repository to a project. Its history moves with it.
The session has no repository
Not in a git checkout, or an ad hoc request with no code behind it. The work goes to the organisation's default project.
A worktree of a repository
The same project as the repository it was made from. A worktree is its own checkout, but it is not its own repository as far as the board is concerned.
A repository is removed from a project
Nothing is deleted. Its cards stay in the project's history, and new reports land outside any project until it is added to one again.
One session touches several repositories
Each report carries its own repository, so each one lands in its own project. The project the session names is the one for the directory it started in.
The service cannot be reached
Reporting is unchanged: reports queue and go when the service answers. teamflow status says project: unknown rather than guessing.
Tracker imports follow the sources
A connection's import scope is the union of every project's sources. Adding a source marks an import as due; removing one stops new imports and deletes nothing that is already on the board.
The outside states at a glance
| State | What happens |
|---|---|
| In no project | Reports land; shown under Outside any project with an option to add it |
| No repository | Goes to the organisation's default project |
| A worktree | The same project as its repository |
| Removed from a project | History stays; new reports land outside |
| Several repositories | Each report lands in its own project |
| Service unreachable | Reporting unchanged; teamflow status says project: unknown |
| Imports | The union of every project's sources |
Add a repository to a project
- Open the project's settings in the dashboard.
- Add the repository.
- If it is refused, the refusal names the project that already holds it. Remove it there first.
Work already reported from that repository appears in the project as soon as the change is saved. Nothing is rewritten and nothing is re-imported.