Skip to content

Commit 49af548

Browse files
treyharristreyharris
authored
Update issue templates for #2904
This is WIP for discussion. Two things (at least) need to be added: 1. A pull request template 2. Where we should point people who have issues with the language that they are having the impulse to express via a doc fix. (There isn’t a one-size-fits-all answer here, since some things will go to rakudo and some to perl6 for instance, but a general rule of thumb should be included in the templates, I think?)
1 parent 58b9ef0 commit 49af548

File tree

6 files changed

+275
-0
lines changed

6 files changed

+275
-0
lines changed

‎.github/ISSUE_TEMPLATE/author-bug-report.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
name: Author bug report
3+
about: For contributors and developers
4+
title: ''
5+
labels: ''
6+
assignees: ''
7+
8+
---
9+
10+
<!-- This is for bugs involving the software used to build the docs. If you are experiencing an issue viewing the docs, please use another issue type. -->

‎.github/ISSUE_TEMPLATE/clarification-request.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
name: Clarification request
3+
about: You’ve found something confusing
4+
title: ''
5+
labels: docs
6+
assignees: ''
7+
8+
---
9+
10+
<!--
11+
Feel free to delete anything that definitely does not apply to your
12+
issue, as well as these comments. (Or don’t, it’s up to you.)
13+
14+
Please paste (a) link(s) from your browser showing the issue (bare
15+
so it can be seen, not buried in a Markdown link).
16+
17+
Often a clarification request has as much to do with _where_ in the
18+
docs something is addressed as _how._ If you think something is
19+
useful but in the wrong place(s), or needs to be in multiple places
20+
because of where different readers will look, say so!
21+
22+
If you're not sure where your request for clarification could be
23+
best dealt with, either provide the URL where you think it should
24+
be, provide multiple possible URLs, or delete the line.
25+
26+
Please don't provide a URL you wish existed that does not -- that
27+
should be in a "New material" request instead.
28+
29+
-->
30+
**Found in URL:** URL-HERE
31+
<!--
32+
Also include the commit hash shown at the bottom of your browser
33+
page, so we know what version you’re looking at. Better yet, include
34+
the entire “From FILE.pod6 at perl6/doc on GitHub, commit a0b1c2d.”
35+
line you’ll find as the first line of every doc page’s footer. -->
36+
**Found at commit:** COMMIT-OR-FROM-LINE-HERE
37+
## The problem
38+
39+
<!--
40+
41+
Please describe the content you feel needs clarification. A quote,
42+
cut and pasted, would be much appreciated (use `> ` or a blockquote
43+
so we can easily see where it begins and ends).
44+
45+
-->
46+
47+
## Suggestions
48+
49+
50+
<!--
51+
If applicable, tell us in "Suggestions" what could be done to solve
52+
the problem, such as "Rephrase the description" or "Change the
53+
example program so it doesn't introduce two unrelated concepts at
54+
once."
55+
56+
Please note we do not have the ability to add diagrams at present
57+
aside from the type graphs.
58+
59+
If you don't know how to fix the issue (this _is_ a documentation
60+
site and we expect it to be used by people who are not expert!),
61+
please don't worry about exact fixes. However, even a vague
62+
description of what would help will help us help you to help
63+
everyone!
64+
65+
On the other hand, if you feel you know _exactly_ how to fix the
66+
issue, feel free to submit a pull request if you're comfortable
67+
doing so--see the CONTRIBUTING.md doc for details. We welcome
68+
patches! Note that clarification patches (unlike simple fix patches)
69+
are more likely to require some back-and-forth before being
70+
merged.
71+
72+
Thank you for contributing to the Perl 6 community by reporting
73+
this!
74+
-->

‎.github/ISSUE_TEMPLATE/new-material-request.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
name: New material request
3+
about: Suggest an idea for something to be added to the docs
4+
title: ''
5+
labels: docs, new
6+
assignees: ''
7+
8+
---
9+
10+
<!--
11+
Feel free to delete anything that definitely does not apply to your
12+
issue, as well as these comments. (Or don’t, it’s up to you.)
13+
14+
If your request has to do with an addition to existing material,
15+
please paste (a) link(s) from your browser showing the issue (bare
16+
so it can be seen, not buried in a Markdown link).
17+
18+
Please note this is _not_ the place to request a new feature be
19+
added to the Perl 6 language--even a small change, like an
20+
additional multi variant or a tweak to a method parameter. We
21+
only document the language as it is today.
22+
23+
If you're not sure where your request could be best dealt with,
24+
either provide the URL where you think it should be, provide
25+
multiple possible URLs, or delete the line. If you just have an idea
26+
of the section ("Language," "Types", etc.) include that in "The
27+
problem" below.
28+
29+
Please don't provide a URL you wish existed that does not -- if you
30+
have an idea for one, please provide it in "Suggestions" below
31+
instead.
32+
33+
-->
34+
**Should be in URL:** URL-HERE
35+
36+
## The request
37+
38+
<!--
39+
Please describe the content you feel needs to be added. As much
40+
specificity as possible is appreciated. For example, if you thing a
41+
new code example is what is called for, or new text, or both, or a
42+
new tutorial, say so.
43+
44+
Please note we do not have the ability to add diagrams at present
45+
aside from the type graphs.
46+
47+
If you don't know how to fix the issue (this _is_ a documentation
48+
site and we expect it to be used by people who are not expert!),
49+
please don't worry about exact fixes. However, even a vague
50+
description of what would help will help us help you to help
51+
everyone!
52+
53+
On the other hand, if you feel you know _exactly_ how to fix the
54+
issue, feel free to submit a pull request if you're comfortable
55+
doing so--see the CONTRIBUTING.md doc for details. We welcome
56+
patches! Note that clarification patches (unlike simple fix patches)
57+
are more likely to require some back-and-forth before being
58+
merged.
59+
60+
Thank you for contributing to the Perl 6 community by reporting
61+
this!
62+
-->

‎.github/ISSUE_TEMPLATE/operational-issues.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
name: Operational issues
3+
about: Website and hosting-related issues
4+
title: ''
5+
labels: site
6+
assignees: ''
7+
8+
---
9+
10+
<!-- This issue type is mostly for contributors and developers. If you are seeing an issue with the website and you’re not involved in this project, you probably want a different issue type.
11+
12+
Also, note that the site is available in at least two places: https://docs.perl6.org/ and https://perl6docs.github.io/ (and the latter will usually be more up to date).
13+
14+
-->

‎.github/ISSUE_TEMPLATE/something-is-incorrect.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
name: Something is incorrect
3+
about: A code sample, signature or definition, heading or title, some prose, or formatting
4+
is wrong
5+
title: ''
6+
labels: bug
7+
assignees: ''
8+
9+
---
10+
11+
<!--
12+
Feel free to delete anything that definitely does not apply to your
13+
issue, as well as these comments. (Or don’t, it’s up to you.)
14+
15+
FIRST!: Check the site at https://perl6docs.github.io/ rather than
16+
docs.perl.org; you may find the issue already fixed—the
17+
perl6docs.github.io site is updated more frequently.
18+
19+
Please paste (a) link(s) from your browser showing the issue (bare
20+
so it can be seen, not buried in a Markdown link): -->
21+
**Found in URL:** URL-HERE
22+
<!--
23+
Also include the commit hash shown at the bottom of your browser
24+
page, so we know what version you’re looking at. Better yet, include
25+
the entire “From FILE.pod6 at perl6/doc on GitHub, commit a0b1c2d.”
26+
line you’ll find as the first line of every doc page’s footer. -->
27+
**Found at commit:** COMMIT-OR-FROM-LINE-HERE
28+
## The problem
29+
30+
<!--
31+
Please state clearly in "The problem" whether you are reporting a
32+
problem with the site (something does not show up in the search
33+
drop-down menu or a page is missing, for instance), documentation
34+
text or examples that are missing or should be improved or
35+
something else. Please describe the problem as clearly as possible.
36+
37+
If it is a formatting issue, we’d appreciate an inline screenshot
38+
from your browser. (On most operating systems, you can simply drag
39+
a screenshot image from your file browser into this text box at
40+
the place you want it to appear.) Annotating and/or cropping the
41+
image to show the problem in context, but without unnecessary clutter
42+
like your browser interface, is appreciated though not required.
43+
44+
-->
45+
46+
## Suggestions
47+
48+
49+
<!--
50+
If applicable, tell us in "Suggestions" what could be done to
51+
solve the problem, such as "Rephrase the description" or "Use an
52+
example program that actually runs".
53+
54+
If you don't know how to fix the issue (this _is_ a documentation
55+
site and we expect it to be used by people who are not expert!)
56+
please don't worry about exact fixes. However, if you can't even
57+
think of what you'd like to see instead (e.g., "working code", "a
58+
correct return type"), you may be using the wrong issue type and
59+
should consider a different one.
60+
61+
On the other hand, if you know _exactly_ how to fix the issue
62+
(such as fixing a routine signature), feel free to submit a pull
63+
request if you're comfortable doing so--see the CONTRIBUTING.md
64+
doc for details. We welcome patches!
65+
66+
Thank you for contributing to the Perl 6 community by reporting this!
67+
-->

‎.github/ISSUE_TEMPLATE/something-s-incorrect.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
name: Something’s incorrect
3+
about: A code sample, signature or definition, heading or title, some prose, or formatting
4+
is wrong
5+
title: ''
6+
labels: ''
7+
assignees: ''
8+
9+
---
10+
11+
## The problem
12+
13+
**Found in URL:**
14+
**Found at commit:**
15+
16+
<!--
17+
18+
Describe the issue here. Please include a link from your browser (bare so it can be seen, not buried in a Markdown link) showing the issue. Also include the commit hash shown at the bottom of the browser page so we know what version
19+
20+
Check the site at https://perl6docs.github.io/ rather than docs.perl.org, you may find the issue already fixed—the perl6docs.github.io site is updated more frequently.
21+
22+
If it is a formatting issue, we’d appreciate an inline screenshot from your browser.
23+
24+
For example:
25+
26+
27+
-->
28+
29+
## Suggestions
30+
31+
32+
<!--
33+
34+
The template below contains optional suggestions. If you cannot
35+
provide some information, simply omit it.
36+
37+
Please state clearly in "The problem" whether you are reporting a
38+
problem with the site (something does not show up in the search
39+
drop-down menu or a page is missing, for instance), documentation
40+
text or examples that are missing or should be improved or
41+
something else. Describe clearly the problem and the page where
42+
you found it.
43+
44+
If applicable, tell us in "Suggestions" what could be done to
45+
solve the problem, such as "Rephrase the description" or "Use an
46+
example program that actually runs".
47+
48+
-->

0 commit comments

Comments
 (0)