Large issue guideline

Basically any larger issue should be represented in two ways simultaneously (on GitHub):

1. Multiple smaller issues for specific, focused parts of the larger issue. I.e. the large issue should be split into smaller issues.
2. A "tracking issue" that describes the large issue in general terms and "tracks" the smaller issues. These GitHub issues are identified via the "tracking" label. We don't require "Tracking issue" (or similar) as part of the issue title; the label should suffice.

There is no strict definition of what a "large issue" is. Some indicators are that the issue...

• ...is a long-term issue, which will require at least multiple release-cycles of time to be completed.
• ...can easily or at least sensibly be split into multiple smaller, technically (but not topically) independent sub-issues.

Constraints

Tracking issues are allowed to exist long-term, possibly across multiple releases, but are always meant to be closed eventually. I.e. they are not meant to exist indefinitely (e.g. no "keep documentation up to date" issues).

They are also not meant to arbitrarily group issues that don't share a definite common goal / (non-GitHub) milestone. E.g. it would not make sense to create a tracking issue for a couple of concurrently active yet otherwise unrelated security issues, but it could make sense to create one for the goal of solving many legacy security issues to eventually reach a fully secure release (see examples).

The issue must also have been agreed upon - which is to say that "discussion" issues or feature requests are not immediately "tracking" issues. Only issues that are already actively worked on or accepted by the core development team can qualify as tracking issue.

Nested tracking issues (i.e. tracking tracking issues in other tracking issues) is not forbidden, but should be avoided if possible, since the tracking issues are meant to present the tracking information in concentrated form.

Examples

Some concrete examples for large issues in the project include:

• Fixing all legacy security flaws. This is a sufficiently large issue because there was no real focus on full security in the past and numerous security issues were accumulated as a result. Therefore a tracking issue may be sensible - but once that is completed, future security issues would not need a tracking issue (unless they are large enough to justify that by themselves, of course!).
• Reaching a reasonably high amount of code coverage (i.e. tests) or documentation quality. Both would be similar to the first example: Tracking issues would be relevant since there are many uncovered parts by now, but once that is done, the tracking issue is closed and any (non-large) similar issues created afterwards should stand on their own.
• A generalized forum / comment / messaging system. For example a fully generalized messaging system could include separate issues for the message structure specification, for various front-end implementations (such as a typical forum or unit-specific comments, e.g. for videos) and more. Less general implementations or "stepping stones", e.g. an (initially) specialized forum system that may not require as much time as the generalized form, would also be tracked.

Conceivable new long-term feature issues e.g. for chat P2P decentralization or general offline-usage functionality could warrant tracking issues eventually, but should first be presented as discussion issues or similar, until they are accepted by the team.

Side note: Tracking issues in another project

For usage of tracking issues in another project, see for example the Rust language main repository's tracking label. Their intent is similar, albeit not identical to this guideline. Also note that the Rust project is clearly significantly larger than geli and relies on a lot of specific categorized labels (currently 170) in comparison to geli's relatively small number of generic labels, among many other organizational differences.