Create a GitLab general issue template

[homotechsual]

Overview

I had a call with Craig this morning to discuss how to raise issues etc on GitLab for new contributors - it was useful but it made me realise that we can help out people opening issues with one or more sensible templates for issues to guide people on what information to include in their issue.

So here's a general issue template based on the PR template and this issue of @jaapjansma's https://lab.civicrm.org/dev/core/issues/1345

Before

When filing an issue in Gitlab, you must enter a full description from a blank slate.

After

When filing an issue in Gitlab, you may choose to use a template:

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[artfulrobot]

Looks good but I'd avoid the dev humour: "click the other thing" is exactly what some of my clients write, leaving me guessing what other thing they clicked on. I think more important to give accurate example.

[homotechsual]

Can you think of/suggest an example?

[demeritcowboy]

I think this is a good idea. Some notes:

If it's for new contributors then the default suggestion for civicrm version of "master" might not be helpful. Maybe 5.5.5?

Since triage priority is identifying recent bugs, including a question "When did it start happening?" or "In which version did it first start happening?" might be useful for triage.

How about for the sample reproduction steps:

1. Clicked on Contacts - New Individual.
2. Entered First Name and Last Name and clicked Save.
3. Got an error "Fatal error: Db error". (Please include the full text of the error message. You can remove any private information like passwords.)

I was thinking stack traces are helpful, but don't want to make the template too complicated and if they're new they might need help finding that anyway.

[eileenmcnaughton]

I'm +1 on the general idea. I agree with the points above too

[homotechsual]

Updated and added a couple of other things.

I haven't changed the version - I think our "new contributor" messaging should be consistent regarding reproduction of bugs/issues on Master. Happy to reconsider/go with the flow if we feel different - perhaps "latest" makes more sense than master?

[totten]

Some of these have lists that you can choose from, and some are just one of many possible values. I think it might be a little clearer that you need to fill every item if either... (a) all the fields had multiple examples

* __Web Server:__ _Apache/LiteSpeed/Nginx/..._  
* __CiviCRM Version:__ _Master/5.20.0/5.19.1/5.18.2/..._
* __CMS:__ _Backdrop/Drupal/Joomla/WordPress_
* __CMS Version:__ _1.0/4.5/6.10/7.30/..._
* __Database:__ _MariaDB/MySQL/Percona/Other_
* __Database Versions:__ _5.5/5.7/10.3/10.4/..._

Or all the fields had FIXME:

* __Web Server:__ _FIXME (Ex: Apache, Nginx)_ 
* __CiviCRM Version:__ _FIXME (Ex: 5.19.1)_
* __CMS:__ _FIXME (Ex: WordPress)_
* __CMS Version:__ _FIXME (Ex: 4.5)_
* __Database:__ _FIXME (Ex: MySQL, MariaDB)_
* __Database Versions:__ _FIXME (Ex: 5.7.7)_

[totten]

Capturing the user's "Browser" is also helpful with bug reports.

[homotechsual]

I like the multiple examples one and I'll add browser.

[totten]

In general, I really like this. 👍 It's a good to get all these organized when reporting a problem.

There may be some subtlty about the type/purpose of the issue:

• If one is reporting a problem or bug, then all of these fields make sense.
• If one is (say) adding an API, then some headings are weird. (There are no "Reproduction steps:", though... analogously... there might some hypothetical use-cases to describe. "Current behavior" and "Environment information" would be non-applicable.)

I don't know if Gitlab has a way to specify multiple templates. But if not, then I think the template could just have a little prose to indicate that it's focused on bugs -- and that it's OK to delete non-applicable sections (for other types of issues).

[artfulrobot]

Sideways thought: what if there was a button in CiviCRM that generated the template? Like if we had an extension that made a list of all the tech stuff including the browser.

"Even" I find it offputting when someone wants to know which version of nginx I'm running for something that's batantly nothing to do with nginx. Having an "issue reporting" extension could just do that paperwork for me so I could copy and paste.

• might reduce the barrier to contributing
• might get more accurate data leading to quicker fixes
• we have better control of the template - could ask questions intereactively to generate it.
• we would have space to explain things like gitlab/hub to users.
• (one day could use api to search/report to gitlab!)

[homotechsual]

In general, I really like this. 👍 It's a good to get all these organized when reporting a problem.

There may be some subtlty about the type/purpose of the issue:

• If one is reporting a problem or bug, then all of these fields make sense.
• If one is (say) adding an API, then some headings are weird. (There are no "Reproduction steps:", though... analogously... there might some hypothetical use-cases to describe. "Current behavior" and "Environment information" would be non-applicable.)

I don't know if Gitlab has a way to specify multiple templates. But if not, then I think the template could just have a little prose to indicate that it's focused on bugs -- and that it's OK to delete non-applicable sections (for other types of issues).

This is a general - but yes - adding an additional MD file to that folder creates another template.

[homotechsual]

Updated with latest feedback and renamed to "general-bug-or-issue".

[homotechsual]

Sideways thought: what if there was a button in CiviCRM that generated the template? Like if we had an extension that made a list of all the tech stuff including the browser.

"Even" I find it offputting when someone wants to know which version of nginx I'm running for something that's batantly nothing to do with nginx. Having an "issue reporting" extension could just do that paperwork for me so I could copy and paste.

• might reduce the barrier to contributing
• might get more accurate data leading to quicker fixes
• we have better control of the template - could ask questions intereactively to generate it.
• we would have space to explain things like gitlab/hub to users.
• (one day could use api to search/report to gitlab!)

This is a great idea and we have an internal Drupal module that does this from D8+Civi to our internal helpdesk but the logic is not Drupal specific - throw up an issue on GitLab and tag me and I'll throw something together.

[artfulrobot]

https://lab.civicrm.org/dev/core/issues/1356

[totten]

@MikeyMJCO I've posted some more suggestions in https://github.com/MikeyMJCO/civicrm-core/pull/1. I think most of them are independent, so you could probably cherry-pick if you agree on some and disagree on others.

[homotechsual]

@MikeyMJCO I've posted some more suggestions in MikeyMJCO#1. I think most of them are independent, so you could probably cherry-pick if you agree on some and disagree on others.

I've merged the whole batch - I think they are all good improvements.

[totten]

Cool :)

Merged.

Updated description ("After") to include a screenshot of how Gitlab presents the templates.