Removing bottlenecks from the Scrum process

[0-sv]

It's easy to start coding and open a pull request. However, as it stands, it leads to more discussion than coding. Pull requests can easily take up to three months. Proof:

• Team jobs #258, one month and a week
• Expert mode #232, one month and three weeks
• add conftest utility for validating opa policy files #177, three months

I'd like to leave a breadcrumb trail in this discussion to improve our Scrum process. I assume that one of our roadblocks is that our stories and tasks CAN lead to scope creep if not properly defined. I've discussed this with @Morriz on 25-1-2021 and we want to come up with a pragmatic solution to spend more time on reviewing requirements before starting to code.

Some notes on this topic:

• These times are not given for public humiliation (e.g. to say, wow look at how bad we're doing) or any other form of insult, just an objective measure (time in weeks/months open)
• Maybe it's not a problem (e.g. we add our code very carefully, the code quality is of a high standard, issue is complex, dependence on third-party libraries -- these are the ones I heard, maybe there are more)
• If we implement a solution, we will reduce the quantity of the defined measure (ie. time the pull request is open). However, it is debatable whether removing that bottleneck will not move it somewhere else, unless other bottlenecks are addressed. I think this is generally acknowledged, but it is my concern that the bottleneck should not reside in the open pull request. I don't know if it has lead to any more frustrations, but at least for me, it has been a frustrating experience so far, because the review goes back and forth and at some point it's not clear where we started, where we're going, why we did it in the first place, etc.

Proposed solutions

Add the following snippet to the scrum.md documentation in the developer documentation:

Business requirements of a story cannot be expressed 1-to-1 into functional requirements. The consequence is that we need to refine stories with a review. We will review stories together with the development team in the "Discussions" section of the relevant repository, most likely otomi-core.

After review, a story can be split up into tasks to be executed by a developer. Let's repeat the difference between a story and a task. A story is the translation of business requirements into functional requirements. A task already has functional requirements. In other words, we don't create business requirements for a task. A task also doesn't have the same standards of review as a story does, so it is expected that a task is straightforward to implement. Feel free to start a discussion, though, in case a task is more nuanced than it appears.

There are some additional standards to story reviews. First of all, there is the discussion component. It is expected to link a story to the relevant discussion. There can be multiple stories attached to one discussion. A discussion should serve as a breadcrumb trail to quickly find out what triggered the initial development. Secondly, we prefix discussion titles with a relevant header in caps. The idea behind it is to quickly find the topic for the discussion. There are multiple so far:

- 'REQ': requirements setting
- 'DES': design
- 'BUG': bug

I could see this being added to a document that lives in otomi-core too, curious to hear your thoughts.

I also wonder whether this needs any policing, or how we could better enforce it. Sure, it's part of the developer documentation, however, one needs to know the whole developer documentation to find it, let alone make sense of it. What I often see in public fora would be a sticky post, that could also be convenient (make it portable if I don't interpret that idea wrong).

Every story (template) should have a link to a (relevant) discussion

This could be automated by modifying the unassigned issues repository so it becomes part of the process of creating a new story.

Every story should have acceptance criteria

I started a discussion about this back in #277, but I still want to mention it here. We currently have as part of the "definition of done": add (unit) tests. But I would appreciate a "definition of WELL done". By convention, it's expected to define acceptance criteria as part of the business requirements to satisfy all stakeholders.

Document the Scrum board process actions

There is no process defined for assigning issues (issues can be stories and tasks). The board also has some automation when creating new issues, but it's not documented yet. We also have some process for moving issues to "on hold", but it's not documented yet.

I discussed this briefly with @Morriz, but I want to include everyone in the process and also appreciate everyone's input.

Further discussion

Let's keep this discussion to some of the blocks we can remove with a "sleight of hand". I expect the following from this discussion:

• Agreements on the ideas if any
• Other proposals for removing blocks
• Counterarguments and examples in case of disagreement if any

tl;dr

• Code reviews are taking too long
• Scope creep occurs here and there
• We could have a more elaborate discussion before coding, then it should be more clear what should be "done".
• This could happen in discussions with tags like REQ/DES/BUG.
• There are some optional ideas about a job "well done"

[Morriz]

Great start. Please implement suggestions in docs for REQ|DES. Don't put any BUG in discussion, it should go straight to the issues, same as issue that can be tagged with label "problem" ;)

See below for more feedback:

I could see this being added to a document that lives in otomi-core too, curious to hear your thoughts.

We have otomi-core/adr/* records, and described Architecture Decision Records in the docs.

This could be automated by modifying the unassigned issues repository so it becomes part of the process of creating a new story.

Indeed, we need to update the issue template there.

But I would appreciate a "definition of WELL done".

Code of ours should have tests demonstrating requirements about its intended outcome. That should always be the generic requirement for a DOD regarding tests. How or where that has to fit one needs to learn or build. Communication is key here. Not documentation.

By convention, it's expected to define acceptance criteria as part of the business requirements to satisfy all stakeholders.

We do scrum. Requirements should be demontrated, and we should not waste time on duplicating old skool "acceptance criteria" from requirements. The proposed "requirements review" will result in the story to meet its DOR. The DOR should mention that we want a clear mapping from business to functional requirements before starting work. The demo should then only demonstrate these functional requirements.

[Morriz]

I say get the examples from https://www.scrum.org/resources/blog/walking-through-definition-ready.
And make these changes:

• Small: does NOT need timebox, I favor explanation here: read https://dzone.com/articles/what-right-size-user-story
• Testable: functional requirements are there for test input

[0-sv]

A demo should be given to an audience.

Yes my idea was that we could give developers a reminder that they should give a demo, if you think we shouldn't include it then that's fine too.

[Morriz]

No, it should be on the DOD checklist to give a demo. Just not a link. If we want to have extensive DOR and DOD descriptions somewhere in our docs, great. Then we can put that link all the way at the bottom for reference.

[0-sv]

Yes that is more accurate, I didn't mean a link to a demo specifically, but I'm glad we got more to the point

[0-sv]

We do scrum. Requirements should be demontrated, and we should not waste time on duplicating old skool "acceptance criteria" from requirements. The proposed "requirements review" will result in the story to meet its DOR. The DOR should mention that we want a clear mapping from business to functional requirements before starting work. The demo should then only demonstrate these functional requirements.

I understand your perspective but I still think it is less error-prone than the alternative. I agree with this point of view:

"A team can up their game by asserting further conditions which must be met before work is considered ready for planning. It is reasonable, for example, to expect acceptance criteria to be articulated for a backlog item such as a user story. Without such criteria developers may not really understand the scope of the work or how it will be tested and validated. In fact, it can be hard for developers to truly estimate work at all unless the acceptance criteria are defined. That’s where the meat often is."

I don't know why you feel that acceptance criteria are "old skool". In my opinion it would have saved us a lot of time if I had more awareness of what the scope of work was and how it will be tested & validated (#204). It looked like a small story to me, but it was extended indefinitely. I hope you want to understand how truly frustrating the experience has been.

[0-sv]

What do you guys think of scheduling a demo in advance of working on a feature? I don't know if I speak for everyone, but for me it helps to gain some perspective and have a goal in mind to work towards. I imagine it could solve having pr's in review for too long by giving it an end-date, and also it would give us a moment to give comments, praise and accept the review sooner.

[Morriz]

Sorry, that is going too far. When requirements are clear and DoR is done, one can start work.

[0-sv]

About unit tests, the current definition is:

"- [ ] (Unit) Tests are added with the code"

My concern is that this is too vague. It is like saying: "I did groceries" -- not mentioning there isn't any food for supper.

What do you think about having minimal test coverage (if relevant)? I found this article, it articulates many similar points found in other articles: https://www.guru99.com/test-coverage-in-software-testing.html.

[Morriz]

I don't mind being specific in the docs, but the checklist should only be that: a checklist. It only has to refer to something already described fully in some docs. So being concise in the checklist is fine. Just put the url to the DoD docs right below it

[0-sv]

Reminiscing my earlier post on Slack, I think it wise to have a discussion about pull request size. As it stands in accordance with Scrum methodology we have both a product owner and a team of developers (as well as other roles but they are not relevant to this discussion).

Before I get into my main point, I first want to define the roles of product owner and developer if the reader is unaware.

Product owner vs developer

I quote from a popular StackExchange post:

"PO has to prioritize the backlog (the what part) where as the team decides amount of work that can be delivered in each sprint (the how-much part)."

This is confirmed in the official Scrum Guide:

"The Product Owner is accountable for maximizing the value of the product resulting from the work of the Scrum Team. How this is done may vary widely across organizations, Scrum Teams, and individuals."

If we follow the Scrum process to the letter, the developers should be responsible for the "how-much" part of development. Now whether you're more inclined to fit Scrum into an organization rather than the other way around, it is reasonable to assume that giving the development team more autonomy in this regard will improve our process. I expect that if we can agree before a sprint on the workload and accept pull requests after reviewing the code for what we've done in that allotted time frame, we can start benefitting from the productivity value of working with the Scrum methodology.

Why I think large pull requests will be detrimental to our process

My main point is articulated in an article about pull request size. Whether you agree with it or not, large pull requests will expose us to a lot of errors being introduced. It stands to reason that the larger the pull requests, the more errors, the longer it will take before going through code review.

The developers are aware of how much work is sustainable given the story:

"Agile processes promote sustainable development.
The sponsors, developers, and users should be able
to maintain a constant pace indefinitely.".

Therefore, if we combine developer and product owner into one role, we will maintain a conflict of interest. On the one hand, the product owner wants to deliver bigger, better and fatter features. On the other hand, it is unsustainable for developers, since they do not have enough autonomy to calculate their own workload. I don't know if I speak for myself, but I think with the current process, the expectations for the features are unrealistic.

I would divide product owner and developer (or CTO) into separate roles. This will create an opportunity to negotiate about feature size with a person who can focus their efforts on the business and customer feedback to assess whether the work done had merit to the commercial side of our product.

Any other solutions to improve anything about this situation would be awesome too. I also don't mind if there is a respectful disagreement but I just want to voice my concern.

[Dunky13]

I agree with this.

By separating the roles, the less experiences developers could more easily take on the lighter/easier tasks to familiarize themselves with the system. If the Product Owner could open multiple issues of different size, then I think more tasks can be accomplished more efficiently.

Some refactoring jobs that should take about an hour, maybe two at most with testing, could be done at the end of the day when concentration is already lower compared to earlier in the day. By having these smaller issues explicitly, then the pull request size shouldn't grow with these "small" additions/removals.

[Morriz]

I don't want to waste too much time here discussing what the ideal world looks like. I'd rather expect a plethora of different contributions and make it easy for contributors. We will respond according to what we receive and make suggestions when it is needed.

[0-sv]

discussing what the ideal world looks like

This conclusion is not what I intend to communicate. There is a real frustration here from the developers and dismissing it like that is not fruitful for a constructive discussion.

I'd rather expect a plethora of different contributions and make it easy for contributors. We will respond according to what we receive and make suggestions when it is needed.

I don't disagree with this point of view, but it's not relevant to this discussion.

[Morriz]

Then I got confused with a pull request that is coming from an outside collaborator, because why would we have large PRs when we agreed to make smaller stories and tasks? We already implemented a better process for this. PR size will reflect that. Please lets not revisit what we already agreed on.

[j-zimnowoda]

If PRs are constantly changed then most probably, scope of work was not defined properly.
In my opinion we should focus more on functionality than making code beautiful. Some PRs are reworked for weeks and after merge they do not function as expected. Therefore, I would prefer to spend more time on testing than golden plating the code.

If some one has different style of making a code but it is still functional, then reviewer should honour it instead of enforcing his will.

[0-sv]

Thank you for joining the discussion.

In an attempt to improve this point of view which I share, I proposed to define a "definition of ready", one of which is to make a story "testable" before implementation. See: https://github.com/redkubes/unassigned-issues/pull/148/files#r576276902.

This point of contention hasn't been finished though, see: #300 (reply in thread)

[Morriz]

If some one has different style of making a code but it is still functional, then reviewer should honour it instead of enforcing his will.

I don't think that is an issue actually. Beautification is automated in most of our repos, and we only miss out on that for bash. However, the coding principals should be honored as those are more about quality, readability, maintainability, and such. Not shape. I would not propose to approve "functional" code that does not adhere to coding principals.

[j-zimnowoda]

By saying style I meant that people may develop the same functionality in many different ways. Of course they should adhere to design patterns and best practices.
I noticed that we are wasting a lot of time on

• debating things like for loop over forEach
• refactoring function and variable naming
• adding ad-hoc new functional requirements, even if a given PR could bring a business value without implementing it.

There is always something that could be improved, but responsibility of the reviewer is to evaluate if asking for yet another change brings a significant value. If the answer is not, then let it go.

[Morriz]

• debating things like for loop over forEach

Is that really happening yes? I have not been part of such a discussion. (Of course we favor iterating over a collection with forEach ;p)

• refactoring function and variable naming

Isn't it good to follow conventions? And are we really losing time there?

• adding ad-hoc new functional requirements, even if a given PR could bring a business value without implementing it.

I agree with that, but have to add that a new functional requirement may of course be needed if that was not translated initially from the business requirements (we are human after all). It is ultimately about delivering business value, and the Story should describe its requirements as such. Any missing functional requirements to deliver that should then still be implemented.