How to report an issue

[dalers]

A recent discussion (that could have easily been an issue - IMO ;-) ) caused me to consider what information would help me understand what's going on as quickly as possible (which is of course only for me and will be different from what would help others).

I'm wondering how to steer the creation of an issue down a path that make will make resolving the issue as easy (i.e. efficient) as possible.

To start, I don't see a "Report an Issue" (or words to that effect) link on the weberp.org home page and suggest it be the first item in the "Social Media" section. It would also be helpful to link to the documentation for how to submit an issue (text file? website page? Wiki page?). I'm sure I have seen something before on how to submit an issue but I can't find it now (which prompted this discussion topic).

My personal guidelines are (and I readily admit I'm the worst offender at breaking my own rules):

• Go overboard when reporting an issue or starting a discussion.
• Explain why you are trying to do something and what you expect the results to be. I.e. why is this an issue?
• Don't assume anything is obvious (it only is to you) and do assume you are talking to a 5-year old. No one will take offence.
• Give the steps to replicate the issue (at least in concept).
• Be exceptionally pedantic if possible.
  • use the exact capitalization and wording when quoting something in the webERP GUI. E.g. a menu name or column heading. Use more words (instead of capitalization) when more emphasis is needed.
  • What is the script name exactly e.g. SystemParameters.php?
  • What is the menu item being accessed exactly e.g. [Setup > General > System Parameters].
• What is the PHP version being used and and the dbms version (it's convenient to have all the related information at hand, and I keep meaning to make a text file with issue boiler plate for myself, but that means even more work....).
• Links to existing related issues or discussions. If you have put the effort into investigating something, please summarize and link to your supporting or source information for the benefit of others. It makes it easier for others to follow the OP's path and (hopefully) come to the same conclusion. Weight is also drawn to your conclusion if there are references you can site. IME there are often repeating edge-case issues that only get worked on for a period of time until something more immediately critical comes up and then issue is tolerated again for a while.

[dalers]

P.S. I propose the Discussion "How To?" category be currated-only and the titles should all be "How to {something.}" ( no question mark).

If I was someone looking for support, it would be extremely convenient if what I saw for titles after clicking the "How To?" category was essentially an FAQ of how to do something. However most of the current titles are more like general discussion topics than a description of how to do something.

• Inventory Category Maintenance
• What is purpose of Manufacturers and Brand Management?
• edi orders update
• Where Do I Find Default Counter Sales Customer Code
• webERP version 5.0.0.rc+12: How To View Profit and Loss? (I'm Just getting 0)
• How to Correctly Define Customer Tax Group
• what company logo resolution and density will just work?

If this cannot be constrained in the repo configuration, should it be the responsibilty of the "core team" to reasssign the category of any new post in the How To? category and move it back should it become a suitable How To (and perhaps edit the title for clarity)? Could there be too many categories?

What do you think?

[timschofield]

Hi @dalers it is possible to create templates for issues in GitHub, though I haven't investigated their use.
I am all for having a link on the website, do you want to issue a PR for this?

Tim

[dalers]

@timschofield I can certainly send a PR but it won't be top of the list.... I'll at least create an issue though. #851

Also I realize using acronyms goes breaks my rule to be verbose but I think the "standard" ones should be accepted because they will get used anyway, they're just too convenient. IIRC, WordPerfect was extremely popular with lawers and contract people in the 80's and 90's (keeping DOS alive long after Windows 3.1 for Workgroups) because each company could have their own unique shortcut-key-phrase file on their Novell network.

I think these are my goto's:

• IIRC - If I Recall Correctly (confident but do not have references that can be cited).
• IANAL - I Am Not A Lawyer (more explit than IMU, I use it when stating something that could be construed as giving legal advice).
• IIUC - If I Understand Correctly (similar to IMU).
• IMO - In My Opinion (reasons are more personal than IMU/IIUC, typically no references can be cited).
• IMU - In My Understanding (more clarity than IMO, typically a conclusion drawn from references but still not "proof") (similar to IIUC).
• OP - Original Poster (the person who started the issue or discussion).

[timschofield]

I have committed two templates, one for bug reporting, and one for a feature request. Treat them just as suggestions to get this moving and propose any changes you see fit. The files are in .github/ISSUE_TEMPLATE/

Thanks
Tim

[dalers]

Thanks Tim. I saw the new templates when I created #853.

I ended up abandoning the templates for #853 because it wasn't as much a bug as a dev question. I had thought about making it a discussion, but I was getting an error message...

I'll look at the templates in more detail next opportunity.