Add template for documentation issues

[glatterf42]

Following up on today's discussion, I prepared an issue form/template based on the two existing documentation issues we already have:

• https://github.com/iiasa/message_data/issues/616 (private)
• Document MESSAGEix workflows for paper "unpack COP28" #379

Please note that I still enable blank issues because that's what we currently have and the only goal of this PR is to help with the creation of documentation issues.

How to review

I hope the file changes show a preview, otherwise, I'm not sure how we could check that everything renders properly. Maybe by merging this first to a fork and opening an issue there.

Yes: If you go to "Files changed" and select "View file" via the three dots on the form file, it will render as a form :)

PR checklist

• Continuous integration checks all ✅
• Add or expand tests; coverage checks both ✅
• [ ] Add, expand, or update documentation. Not changing code.
• [ ] Update doc/whatsnew. Maybe just announce on Slack/during next weekly?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.5%. Comparing base (ed1d61e) to head (c457680).

Additional details and impacted files

@@           Coverage Diff           @@
##            main    #381     +/-   ##
=======================================
- Coverage   74.2%   73.5%   -0.7%     
=======================================
  Files        260     260             
  Lines      21818   21818             
=======================================
- Hits       16198   16050    -148     
- Misses      5620    5768    +148     

see 7 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[glatterf42]

The two "failing" tests were at 99% successful and then were cancelled because of the timeout limit. Do we know why this happens? Our nightly CI also seems to run into this issue frequently of late.

[glatterf42]

It looks like the tests get stuck in tests/model/transport/test_report.py. Sometimes they finish test_simulated_iamc, sometimes they run out of time before finishing that.
Looking at this test more closely, I don't immediately see where this hangup could occur. Most of the code seems simple enough. I suspect the cause is hidden in the simulated_solution() call, but it's going to be tough to troubleshoot this without direct access to a macos system (the timeouts only happen there, though this could still be caused by interference from some other run, maybe somehow).

[khaeru]

Thanks for this!

My initial reaction is that the questions and/or explanatory text should be more direct and explicit about the kind of information people should give, in order to remind them what is appropriate. For example:

Where does the project live?

description: Please tell us where we can find the code and data this project is using.

…could say something like:

Link to or at least name any of the following used for the paper/project:

• GitHub repositories (message-ix-models) or other git repositories (private or public, possibly not on GitHub) and specific branches (main or others), tags.
• Other non-Git locations (e.g. SharePoint folders, cloud drives and files) containing data or code.

I can make some edits later today, in this spirit.

it's going to be tough to troubleshoot this without direct access to a macos system (the timeouts only happen there,

If this is the case, and they pass on other OS, I would support to mark that one test skipif(condition=GHA and system.platform() == "Darwin", reason=...).

[glatterf42]

Sounds good, thanks :)

The tests do pass on both windows and ubuntu, so we can apply the skipif mark, though I don't exactly know the reason why it times out (but of course, we could say reason="Times out for unknown reasons"). I think we can include that in this PR or else in any "transport improvements" PR :)