Skip to content

Commit d4493ae

Browse files
michaeltlombardimichaeltlombardi
authored
(Maint) Prepare for Hacktoberfest (#2312)
* (MAINT) Add markdownlint rules This commit adds markdownlint configuration to the repository in sync with the rules defined in the PowerShell-Docs project. This ensures consistent application of syntax rules across the content. * (MAINT) Add cSpell to repository This change introduces cSpell to the repository for managing spelling across the files. In this initial draft, it adds the upstream dictionary from MicrosoftDocs/PowerShell-Docs and scaffolds a nearly-empty dictionary for the Azure PowerShell modules to make it easier to define terms in the future. It also removes the directive in gitignore so that the .vscode folder will be tracked. * (MAINT) Add extension suggestions This change adds extension suggestions to the repository to ease contributions by providing a list of helpful extensions for writing and maintaining the documentation. * (MAINT) Add issue templates This change introduces GitHub issue templates and the issue picker to the project, enabling an improved UX for people filing issues against the repository. It also includes the issue template for Hacktoberfest 2022, to make participation easier. The configuration for the article issue template is minimal, lacking version or module selection, but those fields can be added in the future if required. * (MAINT) Add Repo automation This change introduces some repository automation from the PowerShell-Docs repositories. In summary: 1. The CODEOWNERS file automatically adds the repository owner(s) as reviewers to incoming PRs. 2. The Pull Request template ensures a standard UX and process for incoming PRs. 3. The checklist workflow uses the PR template to verify that non-admin contributors are following the processes. 4. The expectations workflow uses a static message (defined in the /expectations.md file in the messages folder) to welcome external contributions and set expectations around process for their PR. 5. The dependabot configuration verifies that actions are up to date.
1 parent 3fa40ed commit d4493ae

23 files changed

+1134
-2
lines changed

‎.github/CODEOWNERS

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# https://help.github.com/articles/about-codeowners/
2+
3+
* @mikefrobbins

‎.github/ISSUE_TEMPLATE/00-hacktoberfest.yml

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: "🎃 Hacktoberfest 2022"
2+
description: >-
3+
File a new issue to tackle quality improvement opportunities for Hacktoberfest 2022
4+
title: "🎃 2022: "
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
This issue's related to [Hacktoberfest 2022][01]. For more info, see the meta-issue below:
10+
11+
- MicrosoftDocs/PowerShell-Docs#9257
12+
13+
[01]: https://hacktoberfest.com/participation/
14+
- type: checkboxes
15+
id: prerequisites
16+
attributes:
17+
label: Prerequisites
18+
description: >-
19+
These steps are required. After you've completed each step, check the box for it before
20+
moving on.
21+
options:
22+
- label: >-
23+
**Existing Issue:** Search the existing Hacktoberfest issues for this repository. If
24+
there's an issue that covers the quality area and articles you want to improve, pick a
25+
different quality area or article set. Don't file a new issue for the same work.
26+
Subscribe, react, or comment on that issue instead.
27+
required: true
28+
- label: >-
29+
**Descriptive Title:** Write the title for this issue as a short synopsis. If possible,
30+
provide context. For example, "🎃 2022: Command Syntax in Foo" instead of "🎃 2022: Foo"
31+
required: true
32+
- type: dropdown
33+
id: QualityArea
34+
validations:
35+
required: true
36+
attributes:
37+
label: Quality Areas
38+
description: |
39+
Select one or more quality areas to improve on with your contribution.
40+
41+
For more information, see the relevant section in the meta issue:
42+
43+
- [Aliases][aliases]: Ensure cmdlet aliases are documented
44+
- [Formatting code samples][code-samples]: Ensure proper casing, line length, etc in code samples
45+
- [Formatting command syntax][command-syntax]: Ensure proper casing and formatting for command syntax, including cmdlets, types, etc.
46+
- [Link References][link-refs]: Ensure links in conceptual docs are defined as numbered references
47+
- [Markdown linting][md-linting]: Ensure content follows markdownlint rules
48+
- [Spelling][spelling]: Ensure proper casing and spelling for words
49+
50+
[aliases]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257#aliases
51+
[code-samples]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257#formatting-code-samples
52+
[command-syntax]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257#formatting-command-syntax
53+
[link-refs]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257#link-references
54+
[md-linting]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257#markdown-linting
55+
[spelling]: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257#spelling
56+
multiple: true
57+
options:
58+
- Aliases
59+
- Formatting code samples
60+
- Formatting command syntax
61+
- Link References
62+
- Markdown linting
63+
- Spelling
64+
- type: textarea
65+
id: ArticleList
66+
validations:
67+
required: true
68+
attributes:
69+
label: Article List
70+
description: >-
71+
Specify the articles you are committing to work on, one per line. You can specify each entry
72+
as a path, the article's title, or the link to the article on Learn. If you specify an
73+
article by path for a reference article, such as a cmdlet or about topic, specify the
74+
version segment as `*.*`.
75+
placeholder: |
76+
- reference/*.*/Microsoft.PowerShell.Core/Add-History.md
77+
- Add-History
78+
- https://learn.microsoft.com/powershell/module/microsoft.powershell.core/add-history

‎.github/ISSUE_TEMPLATE/01-article.yml

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
name: "💡 New Document Request/Idea"
2+
description: >-
3+
Suggest a new document or major rewrite of an existing one.
4+
labels:
5+
- doc-idea
6+
- needs-triage
7+
body:
8+
- type: checkboxes
9+
id: prerequisites
10+
attributes:
11+
label: Prerequisites
12+
description: >-
13+
These steps are required. After you've completed each step, check the box for it before
14+
moving on.
15+
options:
16+
- label: >-
17+
**Existing Issue:** Search the existing issues for this repository. If there is an issue
18+
that fits your needs do not file a new one. Subscribe, react, or comment on that issue
19+
instead.
20+
required: true
21+
- label: >-
22+
**Descriptive Title:** Write the title for this issue as a short synopsis. If possible,
23+
provide context. For example, "Document new `Get-Foo` cmdlet" instead of "New cmdlet."
24+
required: true
25+
# Commented out for now - Need to think about how to do versioning/module picking
26+
# - type: dropdown
27+
# id: version
28+
# validations:
29+
# required: true
30+
# attributes:
31+
# label: PowerShell Version
32+
# description: >-
33+
# Select the version or versions of the PowerShell this documentation is for.
34+
# multiple: true
35+
# options:
36+
# - "5.1"
37+
# - "7.0"
38+
# - "7.2"
39+
# - "7.3"
40+
- type: textarea
41+
id: summary
42+
validations:
43+
required: true
44+
attributes:
45+
label: Summary
46+
description: >-
47+
Write a clear and concise description of the proposed document. Why is it needed? What gap
48+
will it fill? Who is the intended audience? What scenarios will it address?
49+
placeholder: |
50+
Try formulating the need for this documentation as a user story.
51+
52+
> As a user of <module>, I need a document about <topic> so that <synopsis of value>.
53+
- type: textarea
54+
id: details
55+
validations:
56+
required: false
57+
attributes:
58+
label: Details
59+
description: >-
60+
If possible, please provide extended details that will add context and help the team write
61+
the documentation.
62+
- type: dropdown
63+
id: type
64+
validations:
65+
required: true
66+
attributes:
67+
label: Proposed Content Type
68+
description: >-
69+
Choose the type or types of documentation required.
70+
multiple: true
71+
options:
72+
- Cmdlet Reference
73+
- About Topic
74+
- Concept
75+
- Other / Unknown
76+
- type: input
77+
id: title
78+
validations:
79+
required: false
80+
attributes:
81+
label: Proposed Title
82+
- type: textarea
83+
id: related_documents
84+
validations:
85+
required: false
86+
attributes:
87+
label: Related Articles
88+
description: >-
89+
Provide a list of links to the documentation page(s) that are related to this request. Use
90+
the markdown list syntax for each item. If the entire article is relevant, just link to the
91+
permalink for its source or the live page. If only a section of the article is relevant, use
92+
the permalink to the lines for the most relevant section of the source or the anchor link to
93+
the nearest header for the relevant content instead of the page itself.
94+
placeholder: |
95+
- https://github.com/MicrosoftDocs/azure-docs-powershell/blob/3fa40ed2b941445d2621d13367960f98f30a8973/docs-conceptual/azps-8.3.0/manage-subscriptions-azureps.md?plain=1#L39-L43
96+
- https://learn.microsoft.com/powershell/azure/manage-subscriptions-azureps#change-the-active-subscription

‎.github/ISSUE_TEMPLATE/02-bug.yml

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: "🐛 Report Documentation issue"
2+
description: >-
3+
Report an issue with current documentation.
4+
labels:
5+
- doc-bug
6+
- needs-triage
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: >-
11+
Use this template to report issues with documentation. This can include typos, technical and
12+
factual errors, grammar, spelling, formatting, presentation, etc.
13+
- type: checkboxes
14+
id: prerequisites
15+
attributes:
16+
label: Prerequisites
17+
description: >-
18+
These steps are required. After you've completed each step, check the box for it before
19+
moving on.
20+
options:
21+
- label: >-
22+
**Existing Issue:** Search the existing issues for this repository. If there is an issue
23+
that fits your needs do not file a new one. Subscribe, react, or comment on that issue
24+
instead.
25+
required: true
26+
- label: >-
27+
**Descriptive Title:** Write the title for this issue as a short synopsis. If possible,
28+
provide context. For example, "Typo in `Get-Foo` cmdlet" instead of "Typo."
29+
required: true
30+
- label: >-
31+
**Verify Version:** If there is a mismatch between documentation and the behavior on
32+
your system, ensure that the version you are using is the same as the documentation.
33+
Check this box if they match or the issue you are reporting is not version specific.
34+
required: true
35+
- type: textarea
36+
id: link_list
37+
validations:
38+
required: true
39+
attributes:
40+
label: Links
41+
description: >-
42+
Provide a list of links to the documentation page(s) that show the problem you are
43+
reporting. Use the markdown list syntax for each item. If you are linking to the source for
44+
the document, please use the permalink to the lines that show the problem. If you are
45+
linking to the live page for the document, please ensure each link is to the nearest header
46+
anchor to the problem instead of the page itself.
47+
placeholder: |
48+
- https://github.com/MicrosoftDocs/azure-docs-powershell/blob/3fa40ed2b941445d2621d13367960f98f30a8973/docs-conceptual/azps-8.3.0/manage-subscriptions-azureps.md?plain=1#L39-L43
49+
- https://learn.microsoft.com/powershell/azure/manage-subscriptions-azureps#change-the-active-subscription
50+
- type: textarea
51+
id: summary
52+
validations:
53+
required: true
54+
attributes:
55+
label: Summary
56+
description: >-
57+
Write a clear and concise description of the problem.
58+
- type: textarea
59+
id: details
60+
validations:
61+
required: false
62+
attributes:
63+
label: Details
64+
description: >-
65+
If possible, please provide extended details that will add context and help the team update
66+
the documentation. Additional details may not be useful for typos, grammar, formatting, etc.
67+
For technical or factual errors, please include code snippets and output to show how the
68+
documentation is incorrect.
69+
- type: textarea
70+
id: suggestion
71+
validations:
72+
required: false
73+
attributes:
74+
label: Suggested Fix
75+
description: >-
76+
If you have an idea for how to fix the problem you're identifying, include it here.

‎.github/ISSUE_TEMPLATE/config.yml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: 🎃 Hacktoberfest 2022
4+
url: https://github.com/MicrosoftDocs/PowerShell-Docs/issues/9257
5+
about: >-
6+
If you'd like to participate in Hacktoberfest 2022, before filing an issue, check the info
7+
and instructions.
8+
# - name: PowerShell Product Feedback
9+
# url: https://github.com/PowerShell/PowerShell/issues/new/choose
10+
# about: Please open feature requests for current PowerShell here.
11+
# - name: Support
12+
# url: https://learn.microsoft.com/powershell/scripting/community/community-support
13+
# about: PowerShell Support Questions/Help

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# PR Summary
2+
3+
<!--
4+
Delete this comment block and summarize your changes and list
5+
related issues here. For example:
6+
7+
This changes fixes problem X in the documentation for Y.
8+
9+
- Fixes #1234
10+
- Resolves #1235
11+
-->
12+
13+
## PR Checklist
14+
15+
<!--
16+
These items are mandatory. For your PR to be reviewed and merged,
17+
ensure you have followed these steps. As you complete the steps,
18+
check each box by replacing the space between the brackets with an
19+
x or by clicking on the box in the UI after your PR is submitted.
20+
-->
21+
22+
- [ ] **Descriptive Title:** This PR's title is a synopsis of the changes it proposes.
23+
- [ ] **Summary:** This PR's summary describes the scope and intent of the change.
24+
- [ ] **Contributor's Guide:** I have read the [contributors guide][contrib].
25+
- [ ] **Style:** This PR adheres to the [style guide][style].
26+
27+
<!--
28+
If your PR is a work in progress, please mark it as a draft or
29+
prefix it with "(WIP)" or "WIP:"
30+
31+
This helps us understand whether or not your PR is ready to review.
32+
-->
33+
34+
[contrib]: https://learn.microsoft.com/powershell/scripting/community/contributing/overview
35+
[style]: https://learn.microsoft.com/powershell/scripting/community/contributing/powershell-style-guide

‎.github/dependabot.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "github-actions"
4+
directory: "/"
5+
schedule:
6+
interval: "weekly"

‎.github/messages/expectations.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<!-- GHA.Comment.Id.Community.Expectations -->
2+
3+
# Expectations
4+
5+
Thanks for your submission! Here's a quick note to provide you with some context for what to expect
6+
from the docs team and the process now that you've submitted a PR. Even if you've contributed to
7+
this repo before, we strongly suggest reading this information; it might have changed since you last
8+
read it.
9+
10+
To see our process for reviewing PRs, please read our [editor's checklist][contrib-checklist] and
11+
process for [managing pull requests][contrib-managing-prs] in particular. Below is a brief,
12+
high-level summary of what to expect, but our contributor guide has expanded details.
13+
14+
The docs team begins to review your PR if you [request them to][gh-review-request] or if your PR
15+
meets these conditions:
16+
17+
- It is not a [draft PR][gh-drafts].
18+
- It does not have a `WIP` prefix in the title.
19+
- It passes validation and build steps.
20+
- It does not have any merge conflicts.
21+
- You have checked every box in the [PR Checklist](#pr-checklist), indicating you have completed all
22+
required steps and marked your PR as **Ready to Merge**.
23+
24+
You can **always** request a review at any stage in your authoring process, the docs team is here to
25+
help! You do not need to submit a fully polished and finished draft; the docs team can help you get
26+
content ready for merge.
27+
28+
While reviewing your PR, the docs team may make suggestions, write comments, and ask questions. When
29+
all requirements are satisfied, the docs team marks your PR as **Approved** and merges it. Once your
30+
PR is merged, it is included the next time the documentation is published. For this project, the
31+
documentation is published daily at 3 p.m. Pacific Standard Time (PST).
32+
33+
[contrib-checklist]: https://learn.microsoft.com/powershell/scripting/community/contributing/editorial-checklist
34+
[contrib-managing-prs]: https://learn.microsoft.com/powershell/scripting/community/contributing/managing-pull-requests
35+
[contrib]: https://learn.microsoft.com/powershell/scripting/community/contributing/overview
36+
[gh-drafts]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests
37+
[gh-review-request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review

‎.github/workflows/checklist.yml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Checklist
2+
on:
3+
pull_request:
4+
branches:
5+
- main
6+
types:
7+
- opened
8+
- reopened
9+
- ready_for_review
10+
- edited
11+
- synchronize
12+
permissions:
13+
contents: read
14+
jobs:
15+
Test:
16+
name: Verify Status
17+
runs-on: windows-latest
18+
if: |
19+
!contains(github.event.pull_request.title, 'WIP') &&
20+
!github.event.pull_request.draft
21+
defaults:
22+
run:
23+
shell: pwsh
24+
steps:
25+
- name: Verify Checklist
26+
id: verify_checklist
27+
uses: MicrosoftDocs/PowerShell-Docs/.github/actions/verification/checklist/v1@main

0 commit comments

Comments
 (0)