Where we lose
This site is published by the sgit project, which builds and uses Issues-FS. That is a participant's position, not a neutral one, and it is worth stating before anything else on the site is read. What follows is the part a participant usually leaves out: the cases where this approach is the wrong choice.
Five cases where a file-based tracker is the wrong answer
1 · Non-technical reporters
Somebody who does not have the repository, does not use git, and needs to file a bug from a phone. There is no web form, no email gateway and no mobile client. The tracker is only reachable by people who can already clone the repository, which excludes most of the people a real product hears from. A hosted tracker solves this on day one, and Issues-FS does not solve it at all.
2 · Cross-repository work
The tracker lives inside the repository it tracks. Work spanning five repositories therefore lives in five graphs with no edges between them — and none exists anywhere in the ecosystem today. The lexicon was designed to address exactly this and was never built. If your work does not respect repository boundaries, neither will your issues.
3 · Anything needing a query language
Filtering is --type and --status. Anything richer means the Python API or grep. There is no saved search, no report, no burndown, no dashboard. A team that manages by dashboard should buy one.
4 · Scale nobody has tested
The largest live graph is 71 nodes across 84 files. Every claim on this site about the design's properties — legible diffs, per-node merges, walking the tree — is true at that size and untested at ten thousand. One-file-per-node has a known shape of failure at scale, and nothing here has met it.
5 · Permissions
Anybody who can write to the repository can write to any issue in it. There is no per-issue access control, no private issue and no audit trail beyond git history. The writer rule is a convention held by agents, not a permission — nothing enforces it. For a security disclosure process, that is disqualifying.
And three things about the project itself
- Two published packages are empty.
issues-fs-serviceandissues-fs-service-client-pythonresolve on PyPI and contain no code, while their summaries describe a FastAPI server and a Python client. Said plainly on the shipped page, and it is the kind of thing a participant would normally omit. - Every README in the ecosystem is behind the code, and four load-bearing claims in them are false. All four are published with what was measured instead.
- The philosophy has outgrown the implementation. The concept documents now underpin another site and a published book, while the central architectural claim they make — the lexicon — has not been built in six months.
Where it does win, for balance
Three properties that are genuinely hard to get any other way, and each of them follows from the same decision — that the issues are files in the repository.
- The tracker branches with the code. A feature branch carries its own issue state, and merging the branch merges the issue state. No integration, no webhook, no sync job that can be behind.
- It is readable without its own tooling, today and in ten years. A graph written by
issues-fs0.7.0 iscat-able,grep-able andfind-able by anything. There is no export step because there is nothing to export from. - An agent can operate it with no client at all. Three surfaces, and the first needs nothing but a filesystem. That is a different claim from “we have an API”.
The licence position, stated rather than assumed
This is a disclosure page, so the unresolved part is disclosed here too.
| Material | Licence |
|---|---|
This site's content — every page, llms.txt, index.md, the brief pack in briefs/ | CC BY 4.0 |
| This site's code — the build tooling, the stylesheet, the workflow | Apache 2.0 |
| The nine Issues-FS repositories, including all 59 documents | Apache 2.0, and no copyright holder is named anywhere. Every LICENSE ends with the unfilled Copyright [yyyy] [name of copyright owner]; no repository has a NOTICE |
| The Issues-FS-lite specification | CC BY 4.0 at source — it lives in a different repository from the rest, which is stated on the page that publishes it |
| ~29,000 words of imported third-party briefings (≈18% of the corpus) | Unattributed. Cited here, not republished |
One README states that documentation is CC BY 4.0. That sentence is the only occurrence of “CC BY” in the entire corpus, and the repository holding all 59 documents ships Apache 2.0 and says nothing about it. This site does not treat one sentence as backing. Until it is resolved, upstream documents are cited by path and quoted with attribution rather than mirrored — which is why several pages here catalogue a document instead of reproducing it. Requests N1 and N2.
How to check this site rather than trust it
Every load-bearing number here was measured, and every measurement can be re-run:
# the package table
curl -s https://pypi.org/pypi/issues-fs/json | head
curl -s https://pypi.org/pypi/issues-fs-service/json # then unzip the wheel and count
# the graph numbers
find .issues -name issue.json | wc -l
# the CLI surface
pip install issues-fs-cli && issues-fs --helpWhere a claim rests on something you cannot check from outside — a commit count, a submodule count — the source is named on the documents page so you can go and look. A site written by a participant should be checkable, since it cannot be neutral.