Wojciech,

Good points — you're right that the docs don't explain this well enough.

On "organization" — it maps directly to sztab.org.code from the install config. I'll update section 1.4 to call it "installation code" and make that explicit.

On the xx differentiator — this is the key thing the docs fail to explain: it's not a type abbreviation, and it's not random noise either. The design is lifted directly from Cisco's CSC format (e.g. CSCdt123456), where the two-letter segment is a sequential differentiator that rolls forward as the number space fills up. The practical value is temporal: if current issues are being assigned st, then spotting SZTdt12345 tells an experienced engineer immediately that it's an old issue — without looking at any metadata. The two letters encode approximate age by their distance from the current differentiator, and once you've worked with the system long enough you develop an intuitive feel for how fast it moves. That's information you can't get any other way at a glance.

So xr vs fr isn't an inconsistency — neither is meant to abbreviate anything. I'll add a proper explanation to section 1.4 so future readers don't reach the same conclusion. Clearly a docs gap on my part.

On the hyphen — I'll leave it as-is. The hyphen feels helpful when the format is unfamiliar, but once the shape of the ID is internalized — three-char prefix, two-char differentiator, five-digit number — the visual boundaries parse automatically and the hyphen becomes needless baggage. Optimizing for the experienced daily user is the right call.

On redirect tables — stable IDs are simpler precisely because they need no such mechanism. Redirect tables require storage, migration tooling, and a lookup service. Unless cross-installation moves become a concrete requirement, the current approach is the right trade-off.

Rk

Worth adding: the same pattern was used at Juniper (and Netscreen, before Juniper acquired them) — so this isn't a Cisco-specific quirk but a convention that held up across multiple large Bay Area networking companies.

Wojciech,

Good points — you're right that the docs don't explain this well enough.

On "organization" — it maps directly to sztab.org.code from the install config. I'll update section 1.4 to call it "installation code" and make that explicit.

So this is more "the installation" / "the deployment" itself (and doesn't match "organisation" notion from GitHub for example)? Thus for example on "https://tigase.dev/" it would always be TIG? In that case do we even need it?

On the xx differentiator — this is the key thing the docs fail to explain: it's not a type abbreviation, and it's not random noise either. The design is lifted directly from Cisco's CSC format (e.g. CSCdt123456), where the two-letter segment is a sequential differentiator that rolls forward as the number space fills up. The practical value is temporal: if current issues are being assigned st, then spotting SZTdt12345 tells an experienced engineer immediately that it's an old issue — without looking at any metadata. The two letters encode approximate age by their distance from the current differentiator, and once you've worked with the system long enough you develop an intuitive feel for how fast it moves. That's information you can't get any other way at a glance.

So xr vs fr isn't an inconsistency — neither is meant to abbreviate anything. I'll add a proper explanation to section 1.4 so future readers don't reach the same conclusion. Clearly a docs gap on my part.

OK, but the same thing can be achieved by… just using numbers (1 is older than 234 which is older than 985345)? And simply using letters to increase the range (26 letters vs 9 numbers) to avoid issue with excessive numbering?

Though, isn't this just a semi-workaround for the issue caused by having the global ID count for absolutely all issues which would yield VeryLargeNumbers? AFAIR Redmine uses similar concept (each issue has it's own ID; https://www.redmine.org/projects/redmine/issues -> https://www.redmine.org/issues/ as only URL) and we used it at one point.

In a way it's convenient (especially schema wise) but it can result in soaring IDs, which is less than ideal, and I think that due to that most other software moved to per-project ID…

On the hyphen — I'll leave it as-is. The hyphen feels helpful when the format is unfamiliar, but once the shape of the ID is internalized — three-char prefix, two-char differentiator, five-digit number — the visual boundaries parse automatically and the hyphen becomes needless baggage. Optimizing for the experienced daily user is the right call.

I would suggest revisiting the stance: most of the world is familiar with either or - format and suggesting that they should "internalise" some rather obscure format with no actual benefits seems very much counterproductive and indeed this format feels more like a "needless baggage"…

On redirect tables — stable IDs are simpler precisely because they need no such mechanism. Redirect tables require storage, migration tooling, and a lookup service. Unless cross-installation moves become a concrete requirement, the current approach is the right trade-off.

There probably won't ever be "cross installation move" and given that the ID is indeed global there is no need for either redirection tables nor additional ID-prefixes IMHO…

Worth adding: the same pattern was used at Juniper (and Netscreen, before Juniper acquired them) — so this isn't a Cisco-specific quirk but a convention that held up across multiple large Bay Area networking companies.

Right, still I'd argue that number of people that has ever seen this format is absurdly miniscule to the world population that interacts with majority of regular "project tracking software" so IMHO this still counts as "quirk convention" :)

Maybe it would be worth asking Artur and Andrzej to weight in with the opinion?

Wojciech,

Reflecting on this a bit more, I think we're both held hostage by our own experiences here — and both experiences are probably valid for distinct customer bases.

Let me describe the world I'm designing for: a customer running a mixed infrastructure — Cisco switches, Tigase XMPP server, Juniper firewall. Defects and incidents from all of these surface in their NOC dashboard, incident reports, email threads, and git commit messages. When that customer sees CSCdt15667 they instantly know it's a Cisco defect. When they see TGSbr56551 they know it's a Tigase issue. No clicking, no lookup — and that matters at 2am during an outage. Engineers who have worked with Cisco and Juniper products for years have this recognition hardwired. Sztab's org prefix is designed to earn that same recognition over time.

But you're right that a team using Sztab purely as an internal tracker, with no multi-vendor context, would find the prefix redundant. That's a legitimate customer base too, and I don't think either of us is wrong — we're just looking at different customers.

So here's a compromise I think serves both: make the ID format a policy decision at installation time. The installer configures the org prefix (or leaves it empty) and the delimiter (hyphen or none). Once the installation is running and issues start being created, the format is frozen — permanently. This is not a setting that can be changed later, because changing it would invalidate every ID already in existence: in git commits, emails, external bug reports, customer correspondence. The immutability isn't a limitation, it's intentional.

That means you choose your format once, with full awareness of your customer base, and it holds for the life of the installation.

I'll leave my own preference on record: org prefix, no delimiter. But I'm genuinely open to the installer defaulting to whatever serves the broader audience best.

@andrzej.wojcik @kobit what is your opinion?

Rk

As long as a single installation of Sztab is not used by multiple organizations/companies/customers, I think that we wouldn't need organization prefix.

I'm more used to the format we have in 1dev and that we had also in YouTrack, that is project prefix followed by a hypen and then issue number within a project. Due to that I would prefer to keep digits only number and keep hypen as well.

Also, the thing with "issue numbering" or issue referencing that was very weird (and I would say inconvenient for me) is what we have in 1dev. That is project structure that needs to be used for while referencing an issue with a different project, ie. tigase/_server/tigase-http-api#170 just to reference an issue from HTTP API as it is in tigase and _server project. While having project "structure"/"tree" while browsing is nice, being forced to use that in issue reference is problematic. I would prefer to have just http-api-170 or something similar.

On the other hand, while I was thinking about "organization prefix", I can find one use case in which it would be useful. Let's say we have a customer with 3-4 (or more projects) on which we work for him (now I could only reference "Atom" project as an example). It would be useful, if we could have prefixes for customer projects, to identify easily for to which customer this project belongs to. As an example, in our case customer for Atom could have prefix AT, then for atom project issues could be AT-ATO-12321 and for link project (for the same customer) it could be AT-LIN-1231.

That could be useful as we could (by looking on the issue number) identity customer for the issue instead of having to remember to who this project belongs to. Right now we do not have many customers with multiple projects.

Basically, if I would make generic way to generate numbers of the issues, I would say it would be formed by (customer prefix)-(project prefix)-(issue number) where if customer wouldn't be set while creating an issue (if from the project ownership) then while (customer prefix)- part would be skipped.

However, when I think about it longer, it happens some times that customers create issues in our "main projects", so that may not be as needed as I think.

@wojtek @kobit What do you think?

@rk thank you for your clarification and indeed that's a valid use case, though I'm not sure if it's very wide-spread, especially in the context of possible Tygrys/Sztab users.

@andrzej.wojcik +1 on the YT/1dev-short-id (possibly mandatory to setup per project).

Though pondering this a bit more I think our "issue" kinda stems from the fact that we do often cross-commit (have issue in one project and reference it in commit in different project repository) which possibly is more of a policy thing?

I think, before moving forward with ID schema we should think about the structure that we want to support:

• do we want multi-level project structure? On the one hand I find it very convenient (for example all tigase-server projects are under https://tigase.dev/tigase/_server/~children, but it's mostly for Tigase Server with abundance of modules); maybe handling this on "org level" (so top level "username") would be enough?
• do we want to have "organisations" (akin to what github offers)?

One thing for sure: current default IDs from 1dev (tree-structure) are absurdly bad…

Regarding "customer prefix" -- maybe having flatter-structure (username/project or organisation/project could give what you would like: ID from both organisation and project, so a bit of information that 1dev lenghty ID gives without being as verbose? ATOM-ATOM-123, ATOM-LINK-456, TIGASE-SERVER.

Though, going back to the beginning of the comment: maybe we should stick to: "ID is unique within repository/project" and enforce policy that relevant issues are created (copied + linked back) in the repository where the work is done?

Considering work on Atom/Link/Tygrys this would result in Atom/Link issue tracker having more of a "User Story" type of issues and actual implementation issues would be in Tygrys repository?

Though, going back to the beginning of the comment: maybe we should stick to: "ID is unique within repository/project" and enforce policy that relevant issues are created (copied + linked back) in the repository where the work is done?

Considering work on Atom/Link/Tygrys this would result in Atom/Link issue tracker having more of a "User Story" type of issues and actual implementation issues would be in Tygrys repository?

I understand that splitting issues into "user story" and "implementation" could be useful, but it is time consuming and with workload that we have it could be problematic at times.

Also, I could see a "general project" for issue reporting and then fixes being applied without major work being done in the projects code. Creating issue just for that (while would keep things cleaner) would also take time. If we can solve that (skip this part) by just having a project "prefix" in the issue id, that would be more useful (at least for me).

Agreed. Though - does the org/customer prefix really help here? I mean only having project-id+number would be sufficient in most cases I'd say?

@andrzej.wojcik

The core issue with project-prefixed keys is that they encode an assumption that a defect belongs to a single project. In practice that's rarely true. Here is a real example from my Cisco days:

CSCdt65117 — "Performance issue with filtering large number of records"

• Opened against component UI: (CSCdt65117, component: ui, status: N)
• UI team fixes their part and identifies a corresponding backend issue: (CSCdt65117, component: backend, status: N)
• Backend team fixes their part and identifies documentation changes needed: (CSCdt65117, component: doc, status: N)
• Customer tracking CSCdt65117 can see at a glance which team currently owns their problem, without needing to chase anyone for a status update.

One issue key. Three teams. Full history in one place. The status resets on each handoff so the receiving team treats it as a fresh work item to triage — but the audit trail, the comments, the PRs, and the context all accumulate in a single record.

With project-scoped IDs this becomes ATOM-42, BACKEND-91, and DOCS-8 — three issues that someone has to read in sequence, mentally reconstruct the handoff history from, and trust were all kept in sync. If any team forgot to create their linked issue or update their status, context is lost silently.

This is also why the issue model has a Component field. See section 1.4 of the Issue Management & Workflow document — cross-project mobility was a first-order design goal, not an afterthought. A project prefix baked into the key would be semantically misleading the moment the issue moves to its second component.

I understand the concern about cross-project linking overhead — that's a real workflow problem worth solving. But the solution is making component transitions and cross-team handoffs cheap in the UI, not encoding project ownership into the key and working around it with linked issues.

To illustrate why global IDs matter, here is a scenario that is not contrived or hypothetical — this has played out more times than I can count in large enterprise software organizations I’ve been a part of.

A company ships Product A, which is built on APIs from Product B. The customer has no visibility into Product B — it is an internal implementation detail.

Customer finds a security vulnerability in Product A: user passwords are being leaked. They open an issue:

CSCjk23111 | project: A | component: UI | status: New | priority: Critical

Manager of Project A assigns it to Rks:

CSCjk23111 | project: A | component: UI | status: Assigned | priority: Critical

Rks begins triage:

CSCjk23111 | project: A | component: UI | status: Open | priority: Critical

Rks determines the root cause is in an API from Product B and moves the issue to Project B:

CSCjk23111 | project: B | component: api | status: New | priority: Critical

Project B manager assigns it to Andrzej:

CSCjk23111 | project: B | component: api | status: Open | priority: Critical

Andrzej digs into the logs and finds that the developer in Project A did not pass a salt when invoking the API. The salt was optional but its absence had critical security implications — something the API documentation failed to make clear. Andrzej attaches a PR with a code fix and moves the issue to the documentation component, with instructions to return it to Project A once the doc is resolved:

CSCjk23111 | project: B | component: doc | status: New | priority: Critical

The documentation team updates the API documentation and resolves their part. The issue moves back to Project A where the original call site needs to be corrected:

CSCjk23111 | project: A | component: core | status: New | priority: Critical

Project A engineer applies the fix. Issue closed.

One issue. Two projects. Three components. At least four engineers. Multiple status cycles. And throughout all of it, the customer, their account manager, their management chain, and every engineer involved are all tracking a single identifier: CSCjk23111.

Now consider what happens with project-scoped IDs. The issue would need to be recreated when it moves to Project B (new ID), potentially recreated again when it moves to the doc component (or another ID), and recreated again when it returns to Project A (yet another ID). You now have 3-4 IDs for a single customer-reported issue, a chain of manually maintained linked clones, and a customer who has no idea which ID to quote when they call their account manager.

Copying and linking — as has been suggested — does not solve this. It pushes the burden of coherence onto engineers and process, in exactly the high-pressure situations where process breaks down.

The global ID is not an arbitrary choice. It is the only scheme that keeps a single stable thread through the full lifecycle of an issue, however far it travels across the project and component structure.

Rk

I understand you use case, however, we were using a different approach (and are using now).

Let's say we have tigase-server project that depends on http-api and pubsub. For "main" project (tigase-server) customer reports an issue. We usually create separate tasks for projects http-api and pubsub and mark them as a child issues to the issue reported by the customer. That makes those issues visible to the customer (and us) and we can track their status from the master (customer reported) issue.

With this approach we can pass only required information to the child issues in their description to not overload person working on that issue with unnecessary details (or discussions with client). That also (if needed) allows person working on child issue to look into master issue for overview of the original issue if needed.

What I do like about this approach is that I can clearly see the project in which the work was done for the particular issue. To apply to the scenario with ATOM-42, BACKEND-91, and DOCS-8:

• issue master-43 (with discussions with client or description of the original issue)
• issue atom-42 (with parent issue set to master-43)
• issue backend-91 (with parent issue set to master-43)
• issue docs-8 (with parent issue set to master-43)

Andrzej,

That is a valid and well-practiced workflow — the parent/child decomposition works well when the shape of the work is understood upfront. Clean separation of concerns, scoped context per engineer, and clear project attribution are all real benefits.

Let me draw a distinction between two workflows that I think Sztab needs to excel at:

Planning workflow — you understand the problem, you decompose it into child tasks, you assign them to the right projects. Your approach excels here. master-43, atom-42, backend-91, docs-8 — each issue is created deliberately, with known scope, by someone who already understands the work.

Triage workflow — a customer reports a critical security issue. Nobody knows yet where the problem lives. An engineer picks it up, starts digging, and the true owner emerges through investigation. The issue moves organically as understanding deepens. Upfront decomposition isn't possible because the shape of the problem isn't yet known. Under critical priority, at 2am, stopping to create and link child issues before resuming investigation is not acceptable overhead.

Critically, these two workflows are not mutually exclusive. A triage issue can spawn child issues at any point in its lifecycle — the moment an engineer understands enough to decompose the work, they can do so. You do not have to choose between triage fluidity and planning structure; Sztab should support both within the same issue lifecycle.

This discussion has directly influenced what I think Sztab needs next: two distinct first-class issue relationship types.

Related issues — a lightweight bidirectional link between two issues. Informational only, no workflow coupling. Useful when a connection exists but neither issue depends on the other.

Parent/child issues — a structured relationship where child issues exist because of the parent. This is your planning workflow made explicit, and it carries real workflow implications beyond just an ER relationship:

• Child issues spawned directly from the parent UI at any point — during planning or mid-triage — pre-populated with relevant context
• Parent cannot close while children remain open
• Customer visibility on the parent includes child status rollup
• Priority propagation — a Critical parent flags if a child is being treated as Low
• Notifications flowing up when a child changes status
• A rollup view on the parent showing all children and their states at a glance

I am opening that issue now and will tag you on it. Your scenario — Atom, backend, docs — will be the reference use case.

Rk

The global ID is not an arbitrary choice. It is the only scheme that keeps a single stable thread through the full lifecycle of an issue, however far it travels across the project and component structure.

That's true, though in this case you can have simple and nicely readable #23111 instead of messy #CSCjk23111…

Let me draw a distinction between two workflows that I think Sztab needs to excel at:

Planning workflow — you understand the problem, you decompose it into child tasks, you assign them to the right projects. Your approach excels here. master-43, atom-42, backend-91, docs-8 — each issue is created deliberately, with known scope, by someone who already understands the work.

Triage workflow — a customer reports a critical security issue. Nobody knows yet where the problem lives. An engineer picks it up, starts digging, and the true owner emerges through investigation. The issue moves organically as understanding deepens. Upfront decomposition isn't possible because the shape of the problem isn't yet known. Under critical priority, at 2am, stopping to create and link child issues before resuming investigation is not acceptable overhead.

Usually (in our case) when the customer reports an issue it's either in a dedicated customer project or a "helpdesk" project (a "bag" project that holds all email reported issues and customers see only theris or even act only via email).

In that case after the report you carry out the triage in that issue and when you have clearer picture what the issue is a dedicated "fix issue" is created in relevant project.

Crucially when there is a "2am emergency" you are even less concerned about the issue as most likely you would already be in a "firefighting" call.

Reiterating Sztab/Tygrys will most likely be used in teams way smaller than Cisco/Juniper/etc. What's more - it would most likely be used more for planning the work and less for handling constant emergencies, so that aspect of the system should take utmost priority, not the other way around…

Wojciech,

On #23111 vs #CSCjk23111 — that comparison is exaggerated. You stripped the org prefix and the differentiator to make the format look cluttered, then presented a bare number as the clean alternative. A bare number with no org context is not a design choice — it is the absence of one. If you want #23111, that is entirely available — configure the org prefix to empty and the differentiator to none at installation time. The format is configurable precisely because different teams have different needs. What is not configurable is the underlying global ID, because that is what keeps the issue coherent across its lifetime regardless of what is displayed on top of it.

On the helpdesk/bag project model — I appreciate the concrete description of how your team works, but it does not escape the coherence problem, it relocates it. You now have two issues for one customer problem: the original helpdesk ticket the customer is tracking, and the fix issue the engineer is working. Someone has to keep those in sync manually — updating the helpdesk ticket when the fix progresses, closing it when the fix closes, ensuring the customer is not left chasing a ticket that has been superseded. That overhead exists whether or not there is a 2am emergency.

On the 2am scenario — that was not an argument that Sztab is primarily an emergency response tool. It was an illustration of what happens when the true owner of an issue is not known at creation time. That happens in small teams on Tuesday afternoons as readily as it does at Cisco at 2am. The size of the team does not change the nature of the problem.

I will concede this: planning workflow should be the primary design focus for Sztab's target market, and I have already committed to building first-class parent/child support to serve exactly that. But conceding planning priority is not the same as conceding that triage fluidity is unimportant — and it is certainly not a concession that the global ID is the wrong foundation.

Rk

On #23111 vs #CSCjk23111 — that comparison is exaggerated. You stripped the org prefix and the differentiator to make the format look cluttered, then presented a bare number as the clean alternative.

Because in the grand scheme of things prefix and differentiator are irrelevant and thus are only noise/clutter.

A bare number with no org context is not a design choice — it is the absence of one. If you want #23111, that is entirely available — configure the org prefix to empty and the differentiator to none at installation time. The format is configurable precisely because different teams have different needs. What is not configurable is the underlying global ID, because that is what keeps the issue coherent across its lifetime regardless of what is displayed on top of it.

Again 123345 and SDAxd123345 can be the same global ID. Adding letter prefix adds clutter…

And if the deployment is a single organisation then the prefix won't change at any time during it's lifetime which makes it kinda useless.

The only possible time, where I see it could be useful is if you are and external contractor working for two separate organisations and somehow you have to easily see to which the issue belongs but that could be done via myriad of other ways (URL in the browser, address in the email notification)…

On the helpdesk/bag project model — I appreciate the concrete description of how your team works,

That's great, because the notion of the project was creating something that's useful for US :)

but it does not escape the coherence problem, it relocates it. You now have two issues for one customer problem: the original helpdesk ticket the customer is tracking, and the fix issue the engineer is working. Someone has to keep those in sync manually — updating the helpdesk ticket when the fix progresses, closing it when the fix closes, ensuring the customer is not left chasing a ticket that has been superseded. That overhead exists whether or not there is a 2am emergency.

Erm. Have it occurred to you that this separation can be useful: client doesn't have to be informed and updated on absolutely every change in the work being done that's related to the issue (and from our experience it may be even beneficial NOT to inform it)?

But conceding planning priority is not the same as conceding that triage fluidity is unimportant — and it is certainly not a concession that the global ID is the wrong foundation.

The issue is about format proposed format (as the title says: "Issue ID schema") that's IMHO inherently hard to read. Whether the ID is global or per-project is secondary and I don't have strong opinion either way.