Commit 6b1820b5 authored by Nick Thomas's avatar Nick Thomas

Amend the tech debt in follow-ups policy

parent d5ef5597
...@@ -319,23 +319,39 @@ Make sure to mention the merge request that the ~"technical debt" issue or ...@@ -319,23 +319,39 @@ Make sure to mention the merge request that the ~"technical debt" issue or
It's common to discover technical debt during development of a new feature. In It's common to discover technical debt during development of a new feature. In
the spirit of "minimum viable change", resolution is often deferred to a the spirit of "minimum viable change", resolution is often deferred to a
follow-up issue. However, this has limited value unless a commitment to address follow-up issue. However, this cannot be used as an excuse to merge poor-quality
the debt is made. As technical debt reduces development velocity, it's important code that would otherwise not pass review, or to overlook trivial matters that
to keep it under control. don't deserve the be scheduled independently, and would be best resolved in the
original merge request - or not tracked at all!
Before accepting resolution of technical debt in a follow-up issue, maintainers
should check that that fix is not trivial, and that the contributor (or their The overheads of scheduling, and rate of change in the GitLab codebase, mean
team) can commit to scheduling the issue within the next 3 releases. that the cost of a trivial technical debt issue can quickly exceed the value of
tracking it. This generally means we should resolve these in the original merge
Trivial fixes can - and should - be addressed within the same MR. request - or simply not create a follow-up issue at all.
If a commitment to address the issue in the foreseeable future cannot be found, For example, a typo in a comment that is being copied between files is worth
the maintainer must make a value judgement on whether the problem deserves an fixing in the same MR, but not worth creating a follow-up issue for. Renaming a
issue at all. If the commitment is lacking because the issue is neither trivial method that is used in many places to make its intent slightly clearer may be
nor valuable, then perhaps no issue needs to be made after all. If a commitment worth fixing, but it should not happen in the same MR, and is generally not
is lacking because technical debt is being unfairly neglected, then maintainers worth the overhead of having an issue of its own. These issues would invariably
should generally insist on resolution of the issue upfront, to protect be labelled `~P4 ~S4` if we were to create them.
development velocity.
More severe technical debt can have implications for development velocity. If
it isn't addressed in a timely manner, the codebase becomes needlessly difficult
to change, new features become difficult to add, and regressions abound.
Discoveries of this kind of technical debt should be treated seriously, and
while resolution in a follow-up issue may be appropriate, maintainers should
generally obtain a scheduling commitment from the author of the original MR, or
the engineering or product manager for the relevant area. This may take the form
of appropriate Priority / Severity labels on the issue, or an explicit milestone
and assignee.
The maintainer must always agree before an outstanding discussion is resolved in
this manner, and will be the one to create the issue. The title and description
should be of the same quality as those created
[in the usual manner](#technical-and-ux-debt) - in particular, the issue title
**must not** begin with "Follow-up ...".
## Stewardship ## Stewardship
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment