Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Description of description should suggest treating it as a sentence to match the github/docs implementation #32048

Closed
1 task done
jsoref opened this issue Mar 12, 2024 · 4 comments · Fixed by #32411
Closed
1 task done
Labels
communities Content related to Communities content This issue or pull request belongs to the Docs Content team help wanted Anyone is welcome to open a pull request to fix this issue

Comments

@jsoref
Copy link
Contributor

jsoref commented Mar 12, 2024

Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository
https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file#creating-a-repository-for-default-files -- prose for the description of description would be valuable
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#keys -- the description for description should suggest using sentences (the examples are all in sentence form, but descriptive prose is valuable for descriptions of descriptions instead of requiring readers to recognize the pattern)

What part(s) of the article would you like to see updated?

  1. There should be an actual description of the description: field -- there isn't
  2. The examples should consistently use sentences -- they don't (below are the changes necessary for that):
-description: File a bug report
+description: File a bug report.
-      description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
+      description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com).

Additional information

The github/docs repository itself consistently uses sentences:
https://github.com/search?q=repo%3Agithub%2Fdocs%20path%3A%2F%5E%5C.github%5C%2FISSUE_TEMPLATE%5C%2F%2F%20description%3A&type=code

Note that the description: examples in the syntax page consistently use sentences:
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#keys

Note that the presence of a security file will add a row with a sentence description:
image

This isn't really much discussed in
https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository
or even
https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file#supported-file-types

but...

(Anyway, more bugs and PRs to follow)

@jsoref jsoref added the content This issue or pull request belongs to the Docs Content team label Mar 12, 2024
@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team label Mar 12, 2024
@nguyenalex836 nguyenalex836 added waiting for review Issue/PR is waiting for a writer's review communities Content related to Communities and removed triage Do not begin working on this issue until triaged by the team labels Mar 12, 2024
@nguyenalex836
Copy link
Contributor

@jsoref Thanks for opening this issue! I'll get this triaged for review ✨

@Bahman198

This comment was marked as spam.

@nguyenalex836
Copy link
Contributor

@jsoref Thank you for suggesting these updates! ✨ You or anyone else is welcome to submit a PR with these changes.

@nguyenalex836 nguyenalex836 added help wanted Anyone is welcome to open a pull request to fix this issue and removed waiting for review Issue/PR is waiting for a writer's review labels Mar 29, 2024
@docs-bot docs-bot added this to Help wanted in Docs open source board Mar 29, 2024
@CBID2
Copy link
Contributor

CBID2 commented Apr 7, 2024

@jsoref Thank you for suggesting these updates! ✨ You or anyone else is welcome to submit a PR with these changes.

Hi @nguyenalex836! :) I made the PR that addresses this issue. It's #32411

Docs open source board automation moved this from Help wanted to Done Apr 8, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
communities Content related to Communities content This issue or pull request belongs to the Docs Content team help wanted Anyone is welcome to open a pull request to fix this issue
Development

Successfully merging a pull request may close this issue.

5 participants
@jsoref @CBID2 @nguyenalex836 @Bahman198 and others