search

withastro / docs

Astro documentation
https://docs.astro.build/
MIT License
1.23k stars 1.33k forks source link

Suggestion: github issues template form #3277

Closed Waxer59 closed 11 months ago

Waxer59 commented 1 year ago

I suggest adding the issue templates to make the issues more uniform and clearer using github issues template form, I could work on them if you agree with me.

sarah11918 commented 1 year ago

I can't find a good label for this one :sweat_smile: but @Waxer59 let's start the discussion here!

Propose in this issue what you're thinking of and others are welcome to add to the discussion here!

Waxer59 commented 1 year ago

What I propose would be to add something similar to what we have in the Starlight project when opening an issue, make use of the issue forms of GitHub, to classify them better and that the user knows what to contribute to receive

delucis commented 1 year ago

Nice idea @Waxer59! Can also help guide people away from using docs issues as a place for support questions.

One of the nice things you get with this set-up is also extra stuff on the new issue screen — https://github.com/withastro/starlight/issues/new/choose — for example in the Starlight repo:

screenshot of the new issue page showing options to get support and report security issues separately from creating a new issue

One thing we should double check is if we would need to change how our “Give us feedback” component works on the docs site: currently if you choose “Create GitHub Issue” there, it takes the text in the text field and automatically prefills the new issue with it using a query parameter, e.g. https://github.com/withastro/docs/issues/new?title=Example+Issue&body=Example+body. (A quick test replacing docs with starlight in that URL suggests that that lets you bypass the template entirely!)

Waxer59 commented 1 year ago

But the behavior of the github issue form could be replicated in the component and when created within the docs page the user could even fill in fewer fields than required because these could be obtained with the browser or knowing what page it is specifically, an example: an issue form that consists of reporting a bug on a specific page, fields like what page is it on? or browser version and name would not need to be filled in by the user because this data can be obtained without the user specifying them. This would even improve the user experience when creating an issue because it would make it much easier for the user to create an issue, focusing only on writing the fields that describe the bug.

Waxer59 commented 1 year ago

What do you mean by bypassing the issue form? for example if I make a url that is https://github.com/withastro/starlight/issues/new?title=Example+Issue&body=Example+body instead of creating an issue with these parameters it redirects me to the page where it asks me to create an issue with the forms.

delucis commented 1 year ago

Ohhh, interesting! When I follow that link I get a standard new issue form:

Screenshot of the standard GitHub new issue form

I guess that’s something they only allow for admins on the repo. Thank you for double checking!

It looks like we can still prefill data like you suggest though. This URL uses the template, and sets some of the fields: https://github.com/withastro/starlight/issues/new?template=---01-bug-report.yml&title=Example+Issue&bug-description=Example+body&starlight-version=9.9.9&astro-version=9.9.9&package-manager=Santa+Claus

So yup, we can pre-fill some stuff. We’d still need to figure out what questions to ask — I don’t think we want so much diagnostic information though. Someone could create a docs issue about some content and then browser version etc. is not relevant. Would you like to suggest some things that you think would be important to ask? We can also use a template that is just a title and body but lets us show people more context while they create the issue.

Waxer59 commented 1 year ago

I believe that the following forms could be made:

Now I am going to put what I think could be added in each form:

Feature

This is what I think it could be, maybe some fields are not needed or something else is missing.

ElianCodes commented 1 year ago

I'm totally for this! I actually thought we already integrated this a while ago 🤔

sarah11918 commented 1 year ago

One thing I will say is NOT to include a linked PR.

How we encourage people to get involved is to make PRs based on issues, to cut down on PRs that aren't actually helpful or what we want. What some people will then do is make an issue, then immedately make a PR to solve it. And, that's not what we want! :sweat_smile:

We'd like people to file issues so we can evaluate them, and THEN invite a PR or add the help wanted label. So, let's not encourage this in the template. :smile:

sarah11918 commented 1 year ago

I'm also going to push back against "Feature"

I think it's much more likely we're getting issues related to content. Most of our issues are "this is not in docs" and they are otherwise sometimes "this content should be updated"

I'm also not sure we need to worry too much about feature (i.e. site infra) ideas so much as bugs. We should provide a venue that allows people to express that, but it's not typically of the highest priority to us (those are the issues that languish the longest) and they are a small minority of what people actually submit as issues.

So the question is, do we care to differentiate "you should add this to the docs because it's not there" vs "the docs are outdated or need fixing here"?

Waxer59 commented 1 year ago

So, if we remove the link field to a pull request (PR) and also the 'Feature' form, we could add a new template, such as 'Report missing/obsolete content'. Personally, I feel that it would not be necessary to make a distinction between them, as they ultimately serve the same purpose. When missing content is reported, it implies that something new needs to be added, and if obsolete content is reported, it is also required to add or update information to keep the document up to date.

And as previously mentioned, an empty template with a title and a body without further details could be added for problems that cannot be categorized within the existing templates. This would be useful in cases like this one, where the problem does not fit into any specific category

sarah11918 commented 1 year ago

Agreed! I think one for site bugs, one for content, and one "other" is def better than what we had before!

Since you've covered the other ones, for content here are some thoughts:

Waxer59 commented 1 year ago

I consider that these fields would be suitable for the "content" form. Subsequently, the aforementioned "support" and "chat" forms could be added, which should work similarly to those in the Starlight project, to prevent people from using the issues in this repository as support. Once added, it will be necessary to modify the "Give us feedback" component.

sarah11918 commented 1 year ago

(The closest label I had was "site improvement" :smile: )

Waxer59 commented 11 months ago

I have sent a PR adding these changes https://github.com/withastro/docs/pull/3497 , although changes still need to be made in the "Give us feedback" component.

CBID2 commented 11 months ago

Maybe there can be an issue form for topic requests too @delucis(e.g., a tutorial that Astro users want to see more off)?