Add issue templates #501
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| --- | ||
| name: New Documentation Page Suggestion | ||
| about: Suggest a new documentation page | ||
| title: 'New Page: PAGE DESCRIPTION' | ||
| labels: new_docs | ||
|
There was a problem hiding this comment. We already have guide and tutorial labels, and I think we should use it that way, and perhaps add explanation to that. The other repos have documentation issue templates. A page is not even an interesting notion in our context, that's a purely presentational concept. Pages can be generated from other units of information, for instance. There was a problem hiding this comment. A page is intended to be a catch-all for any of the documentation categories so that you don't need a separate issue template to suggest a tutorial, recipe, etc. In that sense, a "page" is any of the documentation artifacts we're trying to produce. I'm fine with not adding a default label at all since we would need to triage |
||
| assignees: '' | ||
|
|
||
| --- | ||
|
|
||
| **Briefly describe the contents of the page** | ||
|
|
||
| **Which type of documentation is this?** | ||
| <!-- Choose from: tutorial, recipe, concept, reference --> | ||
|
|
||
| **Is there prior art? If so, list any relevant materials** | ||
|
There was a problem hiding this comment. Prior art? Is this referring to images and content to embed? Maybe it would be better stated as simply relevant information. If any relevant information already exists, please list below There was a problem hiding this comment. Prior art is the term for "has this or something like it been done before". So this heading is asking, for example, if you're suggesting a new tutorial to link other tutorials on the same subject. "Prior art" isn't actually about media, but I suppose we could use a clearer heading. There was a problem hiding this comment. Actually I forgot that there's a comment right below this heading clarifying what we're asking for. There was a problem hiding this comment. While the sentence below aids in clearing the confusion, a differently formed sentence may reduce the need to clarify from the start. This may also reduce issue across language translation errors that could occur for the reader. |
||
| <!-- List any other pages, blog posts, videos, etc that cover this topic --> | ||
| Original file line number | Diff line number | Diff line change | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,14 @@ | ||||||||||
| --- | ||||||||||
| name: Site Enhancement | ||||||||||
| about: Suggest an improvement to nix.dev | ||||||||||
| title: '' | ||||||||||
| labels: enhancement | ||||||||||
|
There was a problem hiding this comment. Enhancement and improvement should be forbidden. Everything go should be an enhancement of some sort, so that term doesn't add information. If this is about the presentation layer or the site, let's call it that way.
Suggested change
Suggested change
There was a problem hiding this comment. Sure, enhancement was just an existing label There was a problem hiding this comment. Changed the label to |
||||||||||
| assignees: '' | ||||||||||
|
|
||||||||||
| --- | ||||||||||
|
|
||||||||||
| **Suggestion** | ||||||||||
| <!-- What would you like to see changed? --> | ||||||||||
|
|
||||||||||
| **Willing to help?** | ||||||||||
| <!-- Are you willing to help make the change? --> | ||||||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| --- | ||
| name: Task | ||
|
There was a problem hiding this comment. I'm not sure we should have a notion of task. This is a bit of a philosophical issue, and maybe I should write a treatise on this elsewhere, but briefly: Classically issues are problem descriptions, implying some action to be taken (performing a task) in order to solve the problem. Therefore everything here is a task. Tasks can have subtasks, or be part of another task. We cannot express this uniformly in GitHub, but that's not our fault. The general question is: which distinction is relevant here? What is the added information? I think it should be whether the issue description is actionable, for instance has all prerequisite information in place, a definition of done, and possibly an estimate. And that will make it a "good first issue" or simply something that is tractable. I don't object a dedicated template, but the challenge here is distinguishing issues users and occasional contributors will open and things that we process as a team of maintainers. I think I'd prefer a piece of team process rather than an issue template, and then let the team There was a problem hiding this comment. The goal with this template is to get whoever is creating the template to add as much context as possible. I've seen a number of issues in the repo (including those created by me) that don't have much context or info about how to proceed. I want us to be in a place where a casual contributor can look at an issue and have at least some idea what's even required to resolve an issue.
That's why I keep pushing for tracking issues. There should be a way to view one task in the context of the larger deliverable item. I think tracking issues are the least-bad option we have on GitHub without using third-party tools. There was a problem hiding this comment.
I undestand. The point of my comment was raising the question where the template should go. Because there are templates for users to report problems (what we classically use GitHub issues for) and then templates to elaborate a task. I argue the task template maybe should not be an issue template, but rather a section in the handbook or something. Outside contributors cannot meaningfully answer the question "what needs to be done". We can of course leave it as an issue template and then make obvious that this is for internal use, which would also be fine for me. |
||
| about: Record information about a task that needs to be done | ||
| title: '' | ||
| labels: '' | ||
| assignees: '' | ||
|
|
||
| --- | ||
|
|
||
| **What needs to be done?** | ||
| <!-- Describe in detail the work that needs to be done --> | ||
|
|
||
| **Does this require buy-in from anyone? If yes, who?** | ||
|
|
||
| **Is this task blocked by any other tasks? If so, link them here** | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| --- | ||
| name: Tracking Issue | ||
| about: Create a tracking issue for a project or piece of work | ||
| title: Tracking Issue - PROJECT DESCRIPTION | ||
| labels: tracking | ||
| assignees: '' | ||
|
|
||
| --- | ||
|
|
||
| ## Project description | ||
| <!-- Briefly describe the project to provide context for the work that needs to be done --> | ||
|
|
||
| ## Steps | ||
| <!-- List the steps that are required to deliver the project, linking issues and PRs for each step as they are opened --> | ||
|
|
||
| - [ ] Step 1 | ||
| - [ ] Step 2 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this one could be fleshed out a bit more.
We could also link to the contributor guidelines and recommended readings for making this kind of post.
Ask the user what range of nix versions is this info applicable to. (if applicable)
If we are to treat them akin to an academic paper, ask if each statement is linked to the relate sources. (this makes auditing easier).
These are but mere suggestions of common use cases that come to mind. I am open to discussion on this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The intent is that a user that's not a part of the documentation team could also submit one of these issues, so we should keep it lightweight. We can add a section suggesting that they submit as much context possible I don't think most users would fill it out.
This is something we should aim to do, but I think the place for this requirement is in the contributor guidelines, not the issue template for suggesting a new page.
I don't know whether we want to be in the business of writing documentation for old versions of Nix. Maybe that's something we can do someday, but that seems like more work than we can reasonably support at the moment.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe these sections would be more useful in a PR template to aid in those who are actually starting the contribution. In the midst of writing these suggestions, I failed to separate category (Issue, PR respectively).