Re: [openstack-dev] [reno] an alternative approach to known issues
On 09 Feb, Thierry Carrez wrote: > Doug Hellmann wrote: > > 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. > > Yeah it feels like reno would add complexity for little benefit in that > process... Better track debt in a TODO document, or a proper task tracker ? The regular document was my first thought too, but then if we want to create a report on the active TDs, or automate a little the design note creation, mangle and analyze them a little, we will need to build proper tooling from scratch. Also most of this work would probably deprecate the known issue field in the release note. Any new tool that would need to be created, I still imagine it to be pretty similar to reno, at least regarding the process of adding something new: One file per note, together with the code, created from a template, able to be modified over time, and a command to create a report __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [reno] an alternative approach to known issues
Doug Hellmann wrote: > 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. Yeah it feels like reno would add complexity for little benefit in that process... Better track debt in a TODO document, or a proper task tracker ? -- Thierry Carrez (ttx) __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [reno] an alternative approach to known issues
Excerpts from Gabriele Cerami's message of 2018-02-08 22:43:56 +: > 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: > > 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: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [reno] an alternative approach to known issues
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: 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
