Create issue templates

[ferdnyc]

Add templates for bug, feature, and doc issues, based on GitHub's standard templates.

Also create an issue_template.md file for issues of other types, and configure the template selector to allow "blank" issues (which will use that template).

The templates suggest the title prefixes documented in CONTRIBUTING.md, but they'll also apply the relevant issue label (bug, enhancement, or documentation), which makes the prefixing sort of unnecessary/redundant really.

[kvid]

This might be something I would really like! What is the easiest way to test this functionality before merging? Do I have to e.g. cherry-pick your commit into the master branch of my personal fork, and create issues there?

[ferdnyc]

@kvid That's one option, but because I've already merged the branch to my own fork and enabled issues there, you're welcome to also experiment at ferdnyc/WireViz/issues.

[ferdnyc]

GitHub also supports issue forms, a more-complex type of guided issue creation that uses a YAML-defined HTML form; those are also an option. The feature is still technically in beta, but hasn't really changed in years so it seems pretty stable.

[ferdnyc]

Hi @kvid @tobiasfalk, just wanted to ping on whether there's still any interest in this PR? I know it was discussed some in the context of #251, and I see that there was a lot of work going on to shepherd that PR to completion until it finally became #447 and got merged a couple of months back. Totally understandable if there hasn't been time for much else, and maybe still isn't.

No real timeframe here, neither the PR nor my fork is going anywhere so it's still available for testing pre-merge. Just think of this as a once-yearly (or thereabouts) checkin, really. 😉

[tobiasfalk]

I think it is a good idea and merging it would improve hopefully the quality of issues

[kvid]

I'm sorry that I've been offline and not available for contributing for many weeks.

As I wrote earlier, I do like this idea, but unfortunately I've not had time to try it out as I wanted to. Maybe @tobiasfalk, @amotl and others have some time to try it out and describe their experiences (including advantages/disadvantages) in comments here?

Please also suggest a procedure for each developer to test later suggested improvements of the templates.

[ferdnyc]

Totally understandable, as we say at Wikipedia There Is No Deadline.

When it comes to testing suggested changes, the templates are just Markdown documents. Once the basic flow is enabled on the repo and people are familiar with it, just reading them is usually enough to evaluate changes.

With issue FORMS (which the files in this PR aren't) things are somewhat more complex, although again once they're in place, most changes can be evaluated by simple inspection.

To be tested, the templates/forms need to be placed on the default branch of any repo with issues / PRs / Discussions enabled. (There's support for PR and Discussion templates as well.) That can either be the submitter's fork, as I've done, or it could be a separate test repo created for the purpose.

But like I said, in my experience once a repo is over the initial hurdle of setting up templates/forms, inspection & review of future changes is usually sufficient prior to merge. (Any change will only affect the creation of new issues past that point, so worst case they can be tested after merge and reverted or tweaked if anything was overlooked.)

[ferdnyc]

because I've already merged the branch to my own fork and enabled issues there, you're welcome to also experiment at ferdnyc/WireViz/issues.

And in fact, doing so just now I spotted something I'd overlooked — I left the word "template" in the title of the "Documentation issue template", not realizing or forgetting that title is how it shows up in the New Issue template-selection list. So it was offering a choice of creating:

1. Bug report
2. Feature request
3. Documentation issue template
4. Blank issue

...I've now fixed that (to read just "Documentation issue"), both here and in my fork.

[kvid]

I like you contribution very much, and am sorry for not reviewing earlier. I found a few details that might be changed, but please argue against my suggestions or for other alternative changes. Maybe the CONTRIBUTING.md also should be updated to encourage users to use the appropriate issue template?

If possible, I want to merge this PR into the next release, so I changed the destination branch to prepare for that.

[kvid]

These template steps seem to fit to a GUI application, but WireViz is more often used as a CLI tool or imported as a Python library. Maybe suggest a few alternative lists of steps so the user can use what fits best and delete the others?

Maybe also remind the user to supply other info according to CONTRIBUTING.md - e.g.
"The relevant input files unless (preferably) you can demonstrate the same issue using one of the example files. If your input file is large or complex, please try to find a smaller/simplified input that still can reproduce the same issue."

[kvid]

Maybe also suggest copy of text output from WireViz in the terminal, including exception traceback and other error messages, any output file with unexpected contents, etc.?

[kvid]

Suggested change

	- WireViz version:
	- WireViz version (`wireviz -V`):

WireViz supports the -V option (since v0.2)

[kvid]

Suggested change

	- Operating System and version:
	- Operating System and version:
	- In Windows (`ver`):
	- In macOS (`sw_vers`):
	- In modern Linux or FreeBSD (`cat /etc/os-release`):

Maybe you find a better way to write these alternatives to help the user to find the information we need?

[ferdnyc]

One option to be sure you get the info you need/want is to collect it yourselves. For example...

requests has a help submodule that collects relevant system information

>>> from pprint import pp
>>> import requests.help
>>> pp(requests.help.info())
{'platform': {'system': 'Linux', 'release': '7.0.10-201.fc44.x86_64'},
 'implementation': {'name': 'CPython', 'version': '3.14.5'},
 'system_ssl': {'version': '30500050'},
 'using_pyopenssl': True,
 'using_charset_normalizer': False,
 'pyOpenSSL': {'version': '26.1.0', 'openssl_version': '30500050'},
 'urllib3': {'version': '2.7.0'},
 'chardet': {'version': '6.0.0.post1'},
 'charset_normalizer': {'version': '3.4.4'},
 'cryptography': {'version': '48.0.0'},
 'idna': {'version': '3.11'},
 'requests': {'version': '2.33.1'}}

pyproj has something similar...

>>> import pyproj
>>> pyproj._show_versions.show_versions()
pyproj info:
    pyproj: 3.7.2
PROJ (runtime): 9.8.1
PROJ (compiled): 9.7.1
  data dir: /usr/share/proj
user_data_dir: /home/ferd/.local/share/proj
PROJ DATA (recommended version): 1.24
PROJ Database: 1.6
EPSG Database: v12.029 [2025-10-02]
ESRI Database: ArcGIS Pro 3.6 [2025-12-01]
IGNF Database: 3.1.0 [2019-05-24]

System:
    python: 3.14.5 (main, May 11 2026, 00:00:00) [GCC 16.1.1 20260501 (Red Hat 16.1.1-1)]
executable: /usr/bin/python3
   machine: Linux-7.0.10-201.fc44.x86_64-x86_64-with-glibc2.43

Python deps:
   certifi: 2026.1.4
    Cython: 3.2.4
setuptools: 80.10.2
       pip: 26.0.1

If something like that were added to WireViz, you'd still have to have more detailed requests for information, for users of older versions. But you could instruct up-to-date users to do something like,

<!-- Or just open an interactive Python session,
     run the following commands, and paste the output:

import wireviz.debug
print(wireviz.debug.sysinfo())

-->

...and you'd be sure to get exactly the relevant data you need. In time, as versions that lacked the module aged out of support, the template could be simplified to just ask for info collected that way, always.

[kvid]

I agree. I added a simple version of this for a particular problem we had earlier: https://github.com/wireviz/WireViz/blob/v0.4.1/src/wireviz/wireviz.py#L424

I have considered adding such info to the output of wireviz -V, but I fear it might be too verbose. Maybe something like wireviz -VV is better, and we would then also probably need to execute os.system("dot -V") or subprocess.run("dot -V".split()) to print the Graphviz version.

However, as you write, we still need to help users provide this info for a while after adding such a feature because they might not run the latest version.

[ferdnyc]

and we would then also probably need to execute os.system("dot -V") or subprocess.run("dot -V".split()) to print the Graphviz version.

You could, but the graphviz module will do it for you.

>>> import graphviz
>>> graphviz.version()
(14, 1, 4)

[ferdnyc]

@kvid No need to apologize, I completely understand people's time is limited. Having the PR open has been no burden on me, it's here for whenever. If whenever is now/soon, then all the better.

Maybe the CONTRIBUTING.md also should be updated to encourage users to use the appropriate issue template?

That's an option, sure. Alternatively, it's possible to disable the blank issue option, so that users have no CHOICE but to use one of the templates, in which case there's really no need.

As long as the templates cover all of the possible types of issues that someone may need to open, that's often a good way to go.

(But there may need to be more than just these three templates, to fully cover those bases. For example, perhaps a planning/internal issue template for project administrative issues? Just as one example of the type of issue that might otherwise necessitate using the blank (non-)template.)

[kvid]

I'm impressed by your super-quick reply, even at a sunday, when people often relax and stay away from the computer! 😄

I vote for keeping the blank template to allow any type of issue, but encourage the use of the other templates when possible.

Now, I need to return to the work waiting for me in our yard and garden - while the weather is nice.