Improving our issue descriptions

Hello everyone,

I would like to propose a change in our GH templates, especially to our stories and tech debt issues.

Currently we have an acceptance criteria section that is either never added (because people use the feature template to create stories) or things added there are vague like “this page should work as usual:grin: ).

We tend to go along with this because with time we know each other and the tool, so we read between the lines. But new dev and tester don’t have this knowledge and need to be guided.

Today as a tester I have 2 problems when I test a story:

  1. Knowing which page we are talking about. Even recently we spoke a lot about Bulk Edit product page. I never noticed that this was the admin/products page English title :smiley: so it took me a while to understand what was going on.

  2. Understanding the scope of the story. Even with mockups, we don’t have the whole user journey described in our issues. So sometimes dev are making choices and I have no idea as a tester if the PO is happy with this or not. A tester shouldn’t have to ask things to the product owner at the testing stage. It is way too late.

Point 2 here :point_up_2: is not a problem when we open Bugs, because we have this very useful section of “Steps to reproduce”, which I absolutely love.

So my major proposal here is to bring these steps to reproduce to the story template as well, as acceptance critera.

I have made an example here: https://github.com/openfoodfoundation/openfoodnetwork/issues/3859

What I like about this habit - with a product point of vue - is that often it helps me see what I’ve forgotten during inception. It is not perfect, in this example here I forgot to specify where the super admin could turn the invoice ON/OFF. A mockup would have been useful in this example. Notice also I used the sentence “as usual” there, so when I say we must improve our stories description I’m talking to myself as well :slight_smile: And maybe it means a review among product people should be added before we start to develop something?

I also believe detailed steps are helping a tester who is not a user to test admin issues. Of course, while developing, a dev will see that other areas need to be tested and can add tests steps to these scenarios for the tester. But at least the initial scope is clearer for everyone.

If we go forward with automated testing it would also help us to feed automated tests.

Notice also I used link/URL rather than page name. It is really helpful, especially again to be sure of which pages we are talking about.

Finally, I would like to propose to drop the feature template on GH and keep it only in discourse. We put this content in epics but we don’t use it at all. We close epics when their linked issues are done, regardless of the success factors. And I don’t think this is a problem. A generic definition of an epic is a group of stories.
As we described in our process here: https://docs.google.com/presentation/d/1El3DjdwqthQYiJ3i1DkyzQlVnzS49omfjO12Ib5tDFA/edit#slide=id.g47c412a157_2_8 we review if we meet the need in discourse. The success factors can be reviewed in discourse only not both in GH and Discourse.
This would help to have only one template to describe stuff.

If I sum up my proposal in actions:

  1. Start adding steps to our acceptance criteria
  2. Start adding URL instead of page name
  3. Add acceptance criteria to tech debt issues
  4. Delete the feature template

What do you think? @danielle @sauloperez @MyriamBoure @lin_d_hop @Kirsten @luisramos0 @maikel @Matt-Yorkley @kristinalim

I f you have other ideas on how to improve our stories, please share!

2 Likes

Totally up for it.

I’d like to add also discuss about ofn-install and other repo’s issues. We have no templates now which leads to poorly written issues hence lack of understading by the whole team. I’m not sure copying the existing templates would work but we could give it a try.

Nice post @Rachel! Steps in a feature request would be great. The URL is useful as well. By the way, the bulk product edit page was recently moved to /admin/products after we removed the old Spree code that was at that URL.

Tech-debt issues are often refactoring that doesn’t change any functionality. So for the tester, everything should look “as usual”. Defining “as usual” in the issue is difficult. We would basically repeat all specifications of potentially affected parts of the code. That’s massive and we don’t actually have a spec document. The best we have our our automated tests which are our specs.

As a developer, I often also don’t know what the product is supposed to do. Writing “as usual” can be a lazy shortcut and means: “I hope I didn’t break anything.” While I would love to have acceptance criteria for tech-debt, I’m not sure how we can do it. I guess we can just pick a couple of example scenarios but we can’t actually cover the change completely.

I’m also not sure about moving the feature template to Discourse. I’m okay with that but I find Github much easier to search, track and prioritise. Plus we have a template. :slight_smile: But I don’t really mind.

Looks great! We may want to incorporate https://github.com/openfoodfoundation/openfoodnetwork/issues/2758 as well while we’re editing templates.

1 Like

All sounds really good to me :slight_smile:

How do we proceed now? Maybe this should documented in the wiki + updating the templates?

@sauloperez yep :slight_smile: I think we need a github admin for updating the templates. Are you up to apply the changes and copy the templates to the other repos?
About the wiki I only see the feature and story template there, so I guess they are updated when you apply changes through the settings menu? https://help.github.com/en/articles/creating-issue-templates-for-your-repository

Can we remove the ‘Default template’? or is it needed?
Is it even possible? @Rachel @sauloperez

@sigmundpetersen I don’t see that option :confused:

I only see it as a dropdown in Zenhub. Could it be something Zenhub is adding?

Yeah looks like it’s the file https://github.com/openfoodfoundation/openfoodnetwork/blob/master/.github/ISSUE_TEMPLATE.md which was the old way github handled templates.

So we need to delete that. I can have a look at submitting a PR :blush: