Should we have issue templates?

(Mod edit: this was originally a PM but we agreed to make it public for wider discussion)

Hi All,

Didn’t get chance to speak to @gwmngilfen too much in Berlin (my fault) but one of the things that I found that made learning Ansible really hard was the lack of reliable help with questions, there are tons and tons of resources out there but a lot are outdated, and incorrect for the questions narrative, one I struggled with early on was down to something that worked in one version and not another (can’t recall what it was). Something that I think would help engage a lot more people would be a sort of quality guardian approach to answers, so that if a user asks a question they can be sure that they answer/approach thats suggested will work for them. I can appreciate how hard this can be in this sort of environment, both from a management and time management perspective to implement. It almost needs a “new user” section with a set of people that can either give specific answers, or verify that an answer is correct

One thing that I implemented many years ago in a company was when a user asked for help for something they would have to fill in a s template post, with information that was likely to variable, like OS version, management agent etc so that when someone else came to answer the ticket they could give an answer that was applicable to the versions in use


Great to have you at Ansible Community Day, @Kevinwincott !

The template approach sounds useful, we can certainly look into that.

great, happy to help in way I can, id like to get more involved in the ansible community, particularly in the speaking side

1 Like

Templates are indeed possible, although in my experience with GitHub Issue templates they are frequently ignored. It’s definitely worth considering though.

Is there any reason to keep this private? @Kevinwincott can I move this to Forum Guide & Feedback ?

yes of course, when ive used templates in the past ive always told people to google GiGo, then fill in the template, seems to prompt less technical people to give complete answers…

Looking back over this (and thanks to @Kevinwincott for letting me publish it) there seems to be two points here:

  1. Can we use templates in Get Help?
  2. Can we verify solutions?

For 1 the answer is sort of. We can have a template that is inserted into each post - however you can only have one. Given the sheer breadth of information that might be relevant to different projects (e.g. compare an issue with a file-in-line playbook to a webhook error on AWX…) it seems difficult to design a useful template for all possible usecases that isn’t just really vague. However, I can see some scope for a very simple thing such as a reminder to include relevant information, etc. Thoughts here?

For 2, the answer is no, at least in the way I think you mean. This is the place for the community to support itself, and all are welcome to give input - indeed, that is the only way this can scale to the number of users Ansible has (as a FOSS project we don’t actually know that number, but my conservative estimate is “low millions”). Having a dedicated team will not scale, I don’t think.

Now, that said, the forum itself provides tools for this - over time. more people will hit that “Solved” button, and the people who are good at solving things will get recognised for it (check these badges out. We can look to giving such people a prominent title (Support Expert, perhaps?) so that people can have confidence in their answers. Does that help address your concern?

I like the idea of a basic template in the help section. I think even a few vague hints can help.

As for a way to help new folks - I wonder if there’s a way we can help new ansible people help other…new ansible people? I tried this on another project and with a couple of mentors in the space, it really worked well. Tho it was for something far less technical than Ansible…

Or maybe we ask for a blog post or How To’ post here that is specifically directed to new Ansible users and gives them links to a curated list of resources that the community feels are accurate and helpful for onboarding new people into Ansible?


@gwmngilfen thats where I was heading in an indirect way :frowning: a method so that if a user asks a question and gets 10 different replies, the ones that come from people who are verified/trusted, their answer can be thought of as true.


They are ignored at times, mostly by inexperienced users.

The follow-up - possibly automated - can be to ask the user to fill in the template, assign the issue to the user and set a label “waiting for user input” or similar.


Good idea. Automation is possible, of course, but not natively - I think we’d have to write a bot or something. However we do have template replies available to staff, so we can make it easy to reply manually.


There’s one other thing we can do, although I’ll have to test how it interacts with a “normal” template…

Using these docs it is possible to create a deeplink for creating a new issue with various fields filled in. That includes possibly filling in the body, for example:

Now we can’t easily make a whole bunch of these links here, but we can encourage the various projects to put this kind of thing in their docs (with a template they can then control, asking for the information they need). Not everyone will get here from there, but again it may help.

1 Like

OK, so I think we need to get this going. How does the following template sound?

Please replace this text with a description of your issue. You should:

  • Include the version(s) of the relevant software tools, libraries, collections etc
  • Include relavant logs from the issue
  • Use backticks (```) to help format your logs and code (easy-to-read posts are easier to answer too!), like this:
- my code!
  • Set at least one tag (the experts follow the tags, so the right people will find you if you tag)

I’m deliberately not mentioning the over-use of Groups, and emphasising tag use instead - drawing attention to the possibility of mentioning a Group might actually increase the use of it. I think we should use replies like this when we see people abusing the feature :slight_smile:

How does that sound?


Sounds good to me, is OS a consideration too though?

Sadly I think that’s a property of “relevant versions” because much of the time it won’t be - it might apply if, say, managing network config or SELinux, but not if interacting with switches or writing an API playbook.

At this point, how about start using the template, and see how it is used? The actual questions asked in the template can be slightly adjusted if it turns out that something is missing, or people misinterpret it, or add too many unnecessary details.

1 Like

Heh, I’ve been doing community too long, always looking for consensus first :slight_smile:

I’ve deployed a template, keep the feedback coming here if we need to tweak it

1 Like

So @utoddl, @briantist @jrglynn2 and I were discussing this a bit in Matrix yesterday. If I recall correctly, there’s interest in knowing what (if any) research a user has already done, especially if that (a) helps them to find the docs, or (b) helps us to understand where the docs could be better.

We’re thinking it might make sense to add something similar to How do I ask a good question? - Help Center - Stack Overflow somewhere (possibly in Guides, FAQs & Howtos?) and then add a short header to the template that encourages people to detail what they’ve already looked at/tried.

Any thoughts folks? Assuming I don’t hear problems, I’ll update the template next week…


I like this idea. It helps users to remember to add more detail to their topics and that will help them get better answers.

1 Like

Hey Greg!

I just discovered this thread yesterday :face_with_peeking_eye:

Looks great to me… +1!

1 Like