Dod

[michaelkleinhenz]

Added suggestion for a DoD and ambient requirements.

[bartoszmajsak]

Here's my point of view:

The code is properly documented with source code comments

This is a bit vague. Most of the comments outlive the actual code and most of the times are redundant. I think only the public facing API should have proper documentation. The rest can be easily done with meaningful methods and descriptive tests.

I would also consider something about code readability and overall quality (which should be a subject of code review as well as automated code analysis).

At the end of the day it's done when it's shipped. All of the bullet points in this document are simply prerequisites :)

Ah, and thanks for reminding me of this thought provoking blog :) http://blogs.agilefaqs.com/2015/01/26/done-with-definition-of-done-or-definition-of-done-considered-harmful/

[ldimaggi]

Suggestion - Change this:
"The code is properly documented with source code comments"

To this:
"The code (including test code) is properly documented with source code comments"

Small point - "criteria" is already plural.

Suggestion - for the ambient requirements, add these:

• Any additions or changes to code do not introduce functional, perofrmance/throughput, or security regressions."

[michaelkleinhenz]

[copying comment from old PR]

To kickoff the discussion, one of the suggestions is that UX implementation is not part of the DoD. That makes sense where UX is not available yet but we are ready to implement the functional reqs. In such a case, a later story would add the UX design. Sounds like a practical thing to do.

The problem with the approach is, that at the time of the story estimation and acceptance at the start of the sprint, it might not be clear if the UX is available or not. This is a problem for the estimation and popped up yesterday already. In some cases we don't know if we can implement the UX in the current sprint or not.

My suggestion for this situation would be:

1. we define in the story if the UX is part of the story or not explicitly based on the then-available information. Both ways are explicitly noted in the story description (UX required/not required).
2. if the UX becomes available for a "no UX required" story while the sprint is running, we consider the implementation like all "added values" of an implementation as a stretch goal that we fit in as time allows.

The real change here would be, that we now state explicitly on every story if UX implementation is required. That would prevent confusion and would make estimation more reliable

[michaelkleinhenz]

[copying comment from old PR, comment by @Mgranfie]

@michaelkleinhenz Not sure if I am following. UX marks our stories in GIT, "Ready for Dev" and notify Joshua and or the active dev. This would signal that the story is ready to go and that the UX Design is done. The links to all the designs and UX stories in JIRA are provided in the GIT story. Anyone can join our JIRA with a RedHat account.

It sounds like we have two cases to consider for Dev:

1. When Dev is ready to implement functionality and there is no UX design ready:

• It would be great to avoid this situation by planning with UX so that we can vet any implementation issues around the design, early on, before implementation, rather than having to go back and make changes.
• Vetting features down to MVP and phased roll outs will help to minimize the chances of design and dev moving out of step. Fast and focused : )
• We can continue to work on coordinating our efforts, and communicating around our story maps.

1. There is a UX design ready:

• UX marks the story in GIT as "Ready for Dev" and tags Joshua and or the Dev on the feature.
• UX places the links to the JIRA story, as well as, the InVision designs.

If the issue of when is the UX marked done for the product, after development, there had been some discussion around this being a verification criteria, that dev and UX meets to review the build and works through any outstanding issues to agreement.

[bartoszmajsak]

The code (including test code) is properly documented with source code comments

@ldimaggi isn't the test a documentation good enough so that it doesn't need any other comments?

[maxandersen]

@Mgranfie Reading @michaelkleinhenz proposal it simply matches as we agreed on a week ago based on the mail from UX sent two weeks: "We're(UX) still looking to support your team for the needs you have, but there might be some items that we collectively decide should move forward without having designs for some features". Thats all there is to it really.

It would be great to avoid this situation by planning with UX so that we can vet any implementation issues around the design, early on, before implementation, rather than having to go back and make changes.

We already now see repeated sprints where UX is not fully ready thus we need to handle this situation more pragmatically. Us saying UX is not absolute required part of DoD does not mean we will skip UX - it is just so we do not by default gets blocked when UX details are not 100% ready.

Anyone can join our JIRA with a RedHat account.

Did we not just agree that the place to share info is on almighty-ux because the jira was too disconnected from the actual development ? Or are you saying that jira will now be driven by the teams userstories instead of UX ones ?
We are trying to stop the split and repetition of stories - not keep having to go back and forth.

[maxandersen]

minor nit, but its planning not plannings ;)

[maxandersen]

this is somewhat automated in core, do we have similar in UI ?

[michaelkleinhenz]

We have, but this is more of a "please also use it" directive :-)

[maxandersen]

this is very subjective. Not sure if it can mean anything but a stated intent.

[michaelkleinhenz]

Yes, the code comments thing is more about that we should be all aware that it makes sense to comment complex code at least to give hints what it is actually doing. Personal experience: I do not generally comment code, but on locations that require complex flows, I casually add code comments to explain what it is supposed to do. That makes debugging/changing a lot easier (even for myself).
That is not something that can be measured or enforced, the goal is simply to make aware that it is helpful to do it. Maybe this needs more explaination.. @bartoszmajsak @ldimaggi

[michaelkleinhenz]

@ldimaggi worked in your changes.

[centos-ci]

Can one of the admins verify this patch?

[maxandersen]

[test]

[Mgranfie]

@michaelkleinhenz @maxandersen Yes, understandable that when UX is not ready, you may need to move ahead. When we have UX, we need to come up with a DOD for the implementation of UX.

[maxandersen]

@Mgranfie can you propose something ?

[maxandersen]

@michaelkleinhenz I noticed this is put in development folder and thus don't show up on the generated site. What was your intention ?

[michaelkleinhenz]

Will change that.

[michaelkleinhenz]

@maxandersen mmh, maybe I don't get something in the build process of devdocs...when I build it using the docker process, the dod as well as the other documents in development/ are compiled and are available linked on the start page. Do they need to be in _blueprints/?

[maxandersen]

Ah, you added the links manually on the index.adoc page - I was looking in the blueprints section ;)

its rather unfortunate we now have three differents ways of adding content, blueprints, ux folder and now this development one.

Anyway, we can clean that up later.

btw. you got these two errors:

asciidoctor: ERROR: planning.adoc: line 50: only book doctypes can contain level 0 sections
asciidoctor: ERROR: planning.adoc: line 50: only book doctypes can contain level 0 sections

remember to start with == not = on the first title ;)

[alexeykazakov]

Closing as outdated.