Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Issue Tracking
Every change to this repository is tracked by a GitHub issue at https://github.com/spacesdrive/twiligent/issues. Features, fixes, refactors, documentation, dependency updates and deployments all count. The issue is opened before the work starts and closed when the work is complete.
The gh CLI is authenticated as spacesdrive; run every command from the repository root.
Lifecycle
Search first.
gh issue list --state open --search "<keywords>". If an open issue already covers the work, use it instead of opening a duplicate.Open the issue before writing code. Title, body and labels follow the format below. A task with several independent parts gets a parent issue plus one sub-issue per part.
Reference it in every commit. Put
Refs #Nin the commit body while the work is in progress. PutCloses #Nin the commit or pull request that finishes it.Report progress. Tick the task list in the issue body as parts finish (
gh issue edit N --body-file <file>). Record decisions, blockers and scope changes as comments (gh issue comment N --body "...").Close it when the work is complete. Complete means the code is committed and pushed, the docs listed in the Documentation Maintenance Policy are updated, and the checks in
docs/workflows/TESTING.mdpass. GitHub closes the issue automatically when a commit containingCloses #Nreachesmain. If it was not closed that way (the work was merged differently, or the issue needed no commit), close it by hand with a summary:gh issue close N --comment "Done in <commit or PR>. <one line on what changed and how it was verified>"Close a parent last. A parent issue closes only after all its sub-issues are closed.
Unfinished work stays open. If a session ends before the work is done, leave the issue open and add a comment with what is finished and what remains. Never close an issue for work that is not done; close it as "not planned" (
gh issue close N --reason "not planned" --comment "...") only when the work is abandoned.
Title and Body
- Title: sentence case, imperative, under 72 characters, no type prefix and no trailing period. "Add rate limiting to the API", not "feat: rate limiter".
- Body: one short paragraph on the problem or goal, then a
- [ ]task list, then a "Done when" line that says how completion is verified. - Bugs also state the steps to reproduce, what happened and what was expected.
- Never paste secrets, tokens,
.dev.varscontents, user emails or other personal data into an issue. Issues on this repository are public.
The templates in .github/ISSUE_TEMPLATE/ give this structure in the GitHub web form.
Labels
| Label | Use for |
|---|---|
enhancement |
New features and capabilities |
bug |
Behaviour that does not match the docs or user expectations |
documentation |
Docs-only work, or the docs part of a larger change |
security |
Hardening, access control, secrets handling, rate limiting |
typescript |
The TypeScript migration and type-only changes |
Add a new label with gh label create <name> --color <hex> --description "<text>" and list it in this table.
Sub-issues
Link a child issue to its parent with the GitHub sub-issues API. It takes the child's numeric id, not its number:
child_id=$(gh api repos/spacesdrive/twiligent/issues/<child-number> --jq .id)
gh api -X POST repos/spacesdrive/twiligent/issues/<parent-number>/sub_issues -F sub_issue_id=$child_id
Pull Requests
Every change goes through a branch and a pull request, because main is protected and refuses direct pushes (see docs/workflows/GIT.md). The body lists Closes #N for every issue it finishes, so merging closes them. The template in .github/pull_request_template.md has the sections.
Roadmap Items
ROADMAP.md lists planned work. When work on a roadmap item starts, open an issue for it and link the issue from the roadmap entry. When the issue closes, move the entry to CHANGELOG.md and remove it from the roadmap.