Open Stack

Excerpts from Gabriele Cerami's message of 2018-02-08 22:43:56 +0000:
> Hi,
> 
> sometimes it happens, while reviewing a patch, to find an issue that
> is not quite a bug, because it doesn't limit functionality, but
> may represent a problem in some corner case, or with some possible
> future modification in some component involved in the patch; it may
> best be described as a weakness in the code, which may happen only under
> certain circumstances.
> The author, for some time or complexity constraint is creating a
> technical debt, or making a micro design choice.
> 
> How to keep track of the issue ? How, after 6 month when there's time
> and bandwidth to look at the problem again, can this note be found and
> issue dealt in the way it deserves ?
> How to help prioritize then the list of issues left behind during the
> duration of a release ?
> Nobody is going to read all the comments on all the merged patches in
> the past months, to find all the objections.
> Also technical debts cannot be treated like bugs, because they have a
> different life span. A bug is opened and closed for good after a while.
> A technical debt may be carried for long time, and it would be perfectly
> natural to mark it as something to just live with, and pay the interest
> for, because the time required to solve it it's not worth it. And
> despite that, it's important to keep track of them because an eventual
> reevaluation of the interests cost or a change in the surroundings (a
> new requirement that breaks an assumption) may lead to a different
> decision after some time.
> 
> The way technical debts are treated right now officially is by adding a
> TODO note inside the code, or maybe adding a "issue" field in release
> notes.
> I would like to expand this TODO note, and the known issue field,
> make it become something more structured.
> I thought about reno, to create a technical debt register/micro design
> document.
> A developer would generate a UUID, put on the code a comment
> 
> # TD: <uuid>
> 
> and then add the description in reno. A simple yaml associative array
> with three or four keys: UUID, description, consequences, options, which
> may describe either the problem or the micro design choice and
> assumption without which the code may show these weaknesses.
> The description would stay with the code, submitted with the same
> patch with which it was introduced. Then when it's time, a report on all
> these description could be created to evaluate, prioritize and
> eventually close the gap that was created, or just mark that as "prefer
> to just deal with the consequences"
> 
> One may later incur in a problem a number of times, find the piece of
> code responsible, and see that the problem is know, and immediately
> raise its impact to request a reevaluation.
> Or we may realize that the code that creates a certain amount of
> weaknesses is going to be deleted, and we can close all the items
> related to it.
> 
> The creation and handling of such items could add too much of a burden
> to the developer, for these reasons, I would prefer to automate some
> part of the creation, for example the UUID generation, date expansion,
> status change on the item.
> 
> I used this, to try out how this automation could work
> 
> https://review.openstack.org/538233
> 
> which could add basic logic to the templates, to automate some of the
> tasks.
> 
> This idea certainly requires refinement (for example what happens when
> the weakness is discovered at a later time), but I would like to
> understand if it's possible to use reno for this approach. Any feedback
> would be highly appreciated.
> 
> Thanks
> 

What makes reno a good fit for this task? It seems like updating a
regular documentation page in the source tree would work just as well,
since presumably these technical debt descriptions don't need to be
backported to stable branches.

Doug