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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
