Add issue templates #501
Add issue templates #501
Conversation
| **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.
It could perhaps be written like so:
Has this idea been previously documented? If so, please provide a list of any relevant materials.
There was a problem hiding this comment.
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.
We could also link to the contributor guidelines and recommended readings for making this kind of post.
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.
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).
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.
Ask the user what range of nix versions is this info applicable to. (if applicable)
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.
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).
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-04-06-documentation-team-meeting-notes-39/27048/1 |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-04-06-learning-journey-working-group-meeting-notes-3/27061/1 |
|
@fricklerhandwerk you mentioned you had some comments you wanted to leave on this, have you had a chance to look this over? |
There was a problem hiding this comment.
Sorry for the delay; I had/have days off and was generally not in a good shape.
I suggest to break this down into smaller PRs concerning the individual issue types. Documentation requests and the information we'd ask for are a thing on their own. How to refine issues until actionable is an entirely different thing.
I'm still on the fence about tracking issues, because I don't think it's meaningful to discern two particular types of issues. Any issue may have sub-issues that have to be resolved first, so really it's a recursive data type. The only thing we may reasonably distinguish are issues that are actionable (leaf nodes), those are really interesting. But that's not about reporting issues, it's about team process, and even tooling can only help so much with that.
| 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.
| labels: enhancement | |
| labels: presentation |
| labels: enhancement | |
| labels: site |
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 site and added a docstring to it.
| 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 new_docs into a category anyway.
| @@ -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
refine existing issues according to that process. But not sure.
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.
Tasks can have subtasks, or be part of another task. We cannot express this uniformly in GitHub, but that's not our fault.
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.
The goal with this template is to get whoever is creating the template to add as much context as possible.
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.
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-04-13-learning-journey-working-group-meeting-notes-4/27255/1 |
I intentionally didn't do that because if someone goes to create an issue with only one issue template merged it will give a weird impression of the type of issues that can be created. I think it makes sense to land a complete package of templates that can then be iterated on if there's something missing or if we decide something isn't providing any value.
If you're working on a larger project and you've just resolved an issue, how do you know the next task related to that project? The board isn't actually much help there because there's a flat list of "no status" items that are unrelated to the given project. I suppose we could use milestones instead, but you can't attach discussion to a milestone, you can only attach discussion to individual PRs or issues. With a tracking issue you can at least put discussion about a project somewhere. To be clear, I don't think we need tracking issues for everything. There's clearly a difference between an issue that requires you to update a link somewhere, and something like "create a series of tutorials for a learning journey" which requires several smaller subtasks that each requires a non-trivial amount of work. |
One can always create free-form issues.
From experience, I have to disagree. In principle, yes, anything can be iterated on, but once something is merged it tends to stick around, and the activation energy to change it substantially is quite high. The community's total capacity to do any particular type of work (such as maintaining issue templates) is surprisingly limited given that the community's total capacity to do work in general is quite huge. Therefore any given thing will change only very slowly, on average. That's why what happens to work well are small, incremental steps. It's certainly a burden on the author of such changes to make them self-contained and still small, but that's the situation. The same is true for any team: we want to focus on doing something specific, and maintaining issue templates is a peripheral task that will drop off the radar once such a PR is merged until the pain is too strong again.
Yeah, tracking issues are fine as a workaround to provide overview of a set of tasks that somehow belong together. I'm now quite convinced though that every issue template here should be in a separate PR so we can discuss them on their own merit. They aren't really related to each other. PS: I really don't want to stall your work, and I know my comments aren't making things faster. My goal is to make the pace and quality of outcomes more predictable, but fact is that the actual, realistic, average pace of development, all things considered, is much slower than you'd think or anyone likes. For more context, here's a great piece of writing on getting things merged, by my Tweag colleague @smelc: https://www.tweag.io/blog/2022-04-14-getting-things-merged/ |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-04-27-documentation-team-meeting-notes-44/27694/1 |
This PR adds issue templates for the following items:
new_docslabel, which needs to be creatednix.devitself? (styling, markup, etc)trackinglabelYou can always create blank/custom issues by selecting "Open a blank issue" at the bottom of the list of issue templates. This list of issue templates isn't meant to be restrictive, it's meant to automate part of the process of keeping track of work that needs to be done with minimal overhead.