Update creating-a-default-community-health-file.md #34270
Conversation
|
Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines. |
github-actions
bot
added
the
triage
Automatically generated comment ℹ️This comment is automatically generated and will be overwritten every time changes are committed to this branch. The table contains an overview of files in the Content directory changesYou may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request.
fpt: Free, Pro, Team |
|
Proof to verify the process:
Link to the demo page: |
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
This comment was marked as spam.
nguyenalex836
added
content
|
@MariusStorhaug Thanks so much for opening a PR! I'll get this triaged for review ✨ |
| {% data variables.product.product_name %} will use and display default files for any repository owned by the account that does not have its own file of that type in any of the following places: | ||
| {% data variables.product.product_name %} will use and display default files for any repository owned by the account that does not have its own file of that type in the following order: | ||
|
|
||
| * The root of the repository | ||
| * The `.github` folder | ||
| * The `docs` folder | ||
| 1. Local repository: | ||
| 1. The `.github` folder. | ||
| 1. The root of the repository. | ||
| 1. The `docs` folder. | ||
| 1. The `.github` repository: | ||
| 1. The `.github` folder. | ||
| 1. The root of the repository. | ||
| 1. The `docs` folder. | ||
|
|
||
| For example, anyone who creates an issue or pull request in a repository that does not have its own CONTRIBUTING file will see a link to the default CONTRIBUTING file. If a repository has any files in its own `.github/ISSUE_TEMPLATE` folder, including issue templates or a _config.yml_ file, none of the contents of the default `.github/ISSUE_TEMPLATE` folder will be used. |
There was a problem hiding this comment.
Actually the original wording is not incorrect at all, as it doesn't even consider any precedence at all;)
If you read the context above and below, it shows that there are some defaults in .github repo, and unless you have a local content in any of the specified places those defaults would kick in, with some rules about using either all or none in the templates config below.
I mean, what you're trying to say is important and well observed, it just doesn't fit into the existing content breakdown (describing what happens if "that does not have its own file of that type") — you may want to reword the surrounding paragraphs too for this to make sense, or document the file order precedence generally, separately from the existing paragraphs?
There was a problem hiding this comment.
I also do agree with the original description. I just want to make it even more clear how it works. Hope the changes are in line with your thoughts. If not, feel free to give specifics on what you want to see changed.
|
|
||
| For example, anyone who creates an issue or pull request in a repository that does not have its own CONTRIBUTING file will see a link to the default CONTRIBUTING file. If a repository has any files in its own `.github/ISSUE_TEMPLATE` folder, including issue templates or a _config.yml_ file, none of the contents of the default `.github/ISSUE_TEMPLATE` folder will be used. | ||
| When a repository does not contain its own file of a specific type, {% data variables.product.product_name %} will look for a default file in the following order: |
There was a problem hiding this comment.
My original note somewhat persists; it's worded "if a local file is not present, the order will be: 1) local file, 2) global file" which contradicts itself;] — so I guess to show there's an order just skipping the opening of the sentence makes it more correct:
| When a repository does not contain its own file of a specific type, {% data variables.product.product_name %} will look for a default file in the following order: | |
| {% data variables.product.product_name %} will look for a default file in the following order: |
| 1. **Within the Local Repository**: | ||
| 1. `.github` folder | ||
| 1. Root of the repository | ||
| 1. `docs` folder | ||
| 1. **Within the `.github` Repository**: | ||
| 1. `.github` folder | ||
| 1. Root of the repository | ||
| 1. `docs` folder |
There was a problem hiding this comment.
I'm not sure "Local" is a correct term here when git is a distributed system — I'd leave that to content triage folks to chime in with some better recommendation (see the original wording how it carefully avoids using any other phrase than just "repository" in pointing to the current repo?)
Maybe to improve scanability:
| 1. **Within the Local Repository**: | |
| 1. `.github` folder | |
| 1. Root of the repository | |
| 1. `docs` folder | |
| 1. **Within the `.github` Repository**: | |
| 1. `.github` folder | |
| 1. Root of the repository | |
| 1. `docs` folder | |
| 1. `.github` folder in the project's repository | |
| 1. Root of the repository | |
| 1. `docs` folder of the project's repository | |
| 1. `.github` folder in the `.github` repository | |
| 1. Root of the `.github` repository | |
| 1. `docs` folder of the `.github` repository |
to explicitly show the lookup is completely linear, not either–or i.e. repo/docs still precedes .github/.github …
|
|
||
| {% data variables.product.product_name %} will use and display default files for any repository owned by the account that does not have its own file of that type in any of the following places: | ||
| You can add default community health files to a public repository called `.github`. {% data variables.product.product_name %} will use and display default files for any repository owned by the account that does not have its own file of that type. The location of these default files determines whether and how they will be used. |
There was a problem hiding this comment.
| You can add default community health files to a public repository called `.github`. {% data variables.product.product_name %} will use and display default files for any repository owned by the account that does not have its own file of that type. The location of these default files determines whether and how they will be used. | |
| You can add default community health files to a public repository called `.github` and {% data variables.product.product_name %} will use and display default files for any repository owned by the account that does not have its own file of that type, or create them directly in the relevant repository for higher specificity. |
| * The root of the repository | ||
| * The `.github` folder | ||
| * The `docs` folder | ||
| ### File Location and Precedence |
There was a problem hiding this comment.
I'd either skip the heading or move it after "… good practices, collaboration" before starting to talk about any actual files and their locations.
| ### File Location and Precedence |
| If no corresponding file is found in the local repository, {% data variables.product.product_name %} will use the default file from the `.github` repository, following the same order of precedence. | ||
|
|
||
| For example, if someone creates an issue or pull request in a repository that does not have its own `CONTRIBUTING.md` file, {% data variables.product.product_name %} will check the local repository first and, if no file is found, it will fall back to the default `CONTRIBUTING.md` in the `.github` repository. | ||
|
|
||
| However, if a repository contains any files in its own `.github/ISSUE_TEMPLATE` folder, such as issue templates or a `_config.yml` file, none of the contents of the default `.github/ISSUE_TEMPLATE` folder in the `.github` repository will be used. This allows repository maintainers to override the default files with specific templates or configurations as needed. |
There was a problem hiding this comment.
to simplify already stated:
| If no corresponding file is found in the local repository, {% data variables.product.product_name %} will use the default file from the `.github` repository, following the same order of precedence. | |
| For example, if someone creates an issue or pull request in a repository that does not have its own `CONTRIBUTING.md` file, {% data variables.product.product_name %} will check the local repository first and, if no file is found, it will fall back to the default `CONTRIBUTING.md` in the `.github` repository. | |
| However, if a repository contains any files in its own `.github/ISSUE_TEMPLATE` folder, such as issue templates or a `_config.yml` file, none of the contents of the default `.github/ISSUE_TEMPLATE` folder in the `.github` repository will be used. This allows repository maintainers to override the default files with specific templates or configurations as needed. | |
| For example, anyone who creates an issue or pull request in a repository that does not have its own `CONTRIBUTING.md` file will see a link to the default `CONTRIBUTING.md` from the `.github` repository. However, if a repository has any files in its own `.github/ISSUE_TEMPLATE` folder, such as issue templates or a `_config.yml` file, none of the contents of the default `.github/ISSUE_TEMPLATE` folder will be used. This allows repository maintainers to override the default files with specific templates or content on per-repository basis. |
Why:
Closes: #34271
What's being changed (if available, include any code snippets, screenshots, or gifs):
Check off the following:
I have reviewed my changes in staging, available via the View deployment link in this PR's timeline (this link will be available after opening the PR).
datadirectory.For content changes, I have completed the self-review checklist.