Rules Hub
Coding Rules Library
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
Don't Turn Docs Files Into a Per-Ticket Changelog
Keep documentation describing current system behavior instead of appending a line per ticket/PR
Bad example
| 1 | // docs/MARKET-DATA.md |
| 2 | // |
| 3 | // - **TICKET-1338** — added the page-type set support. |
| 4 | // - **TICKET-3225** — added instrument-page JSON-LD. |
| 5 | // - **TICKET-3429** — added `license` field on the Dataset JSON-LD |
| 6 | // (see ticket for full context, follow-up needed elsewhere). |
| 7 | // |
| 8 | // Every future PR that touches this file is now expected to remember |
| 9 | // to append one more bullet here, forever, with no owner enforcing it. |
Explanation (EN)
The doc slowly turns into an unofficial changelog: a bullet per ticket, with no clear reader in mind and no mechanism ensuring anyone keeps adding to it. It duplicates information git already tracks better, and it silently goes stale.
Objašnjenje (HR)
Dokument polako postaje neslužbeni changelog: redak po tiketu, bez jasnog čitatelja i bez mehanizma koji osigurava da će itko nastaviti dodavati retke. Duplicira informacije koje git već bolje prati, i tiho zastarijeva.
Good example
| 1 | // docs/MARKET-DATA.md |
| 2 | // |
| 3 | // ## Dataset JSON-LD |
| 4 | // Includes a `license` field: a `CreativeWork` pointing at |
| 5 | // `${origin}/terms` (the data provider has no public license page, |
| 6 | // so we point at our own terms page instead). |
| 7 | // |
| 8 | // Change history for this file lives in git log / PR links, not here. |
Explanation (EN)
The doc only describes the current, real behavior of the system. Anyone wanting the history of why it looks this way can use git blame or the linked PR/ticket — no hand-maintained log to forget about.
Objašnjenje (HR)
Dokument opisuje samo trenutno, stvarno ponašanje sustava. Tko god želi povijest zašto je nešto tako implementirano može koristiti git blame ili povezani PR/tiket — nema ručno održavanog loga koji se zaboravlja ažurirati.
Notes (EN)
If change history genuinely needs to be discoverable, link out to the ticket tracker or rely on git/PR history and blame — don't duplicate it by hand inside a docs file, since hand-maintained lists rot the moment someone forgets to update them.
Bilješke (HR)
Ako povijest promjena stvarno treba biti dostupna, poveži se na tracker zadataka ili se osloni na git/PR povijest i blame — nemoj je ručno duplicirati u docs fileu, jer ručno održavane liste zastare čim netko zaboravi dodati novi redak.
Exceptions / Tradeoffs (EN)
A dedicated CHANGELOG.md following a clear, agreed convention (e.g. Keep a Changelog) for an externally consumed package or library is fine — that is its explicit purpose and it has clear ownership. The problem is bolting an undocumented, informal ticket log onto an unrelated architecture/reference doc.
Iznimke / Tradeoffi (HR)
Poseban CHANGELOG.md po jasnoj, dogovorenoj konvenciji (npr. Keep a Changelog) za paket ili biblioteku koju koriste vanjski korisnici je u redu — to mu je eksplicitna svrha i ima jasnog vlasnika. Problem je kad se neformalni popis tiketa doda na dokument koji opisuje arhitekturu/ponašanje sustava, bez ikakve dogovorene svrhe.