diff --git a/.github/ISSUE_TEMPLATE/01-article.yml b/.github/ISSUE_TEMPLATE/01-article.yml index 7e8f264b2501..8d2fdf659937 100644 --- a/.github/ISSUE_TEMPLATE/01-article.yml +++ b/.github/ISSUE_TEMPLATE/01-article.yml @@ -33,9 +33,8 @@ body: multiple: true options: - "5.1" - - "7.2" - - "7.3" - "7.4" + - "7.5" - type: textarea id: summary validations: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 686e5e7a090b..db5367ad0ae2 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,10 +1,44 @@ # Microsoft Open Source Code of Conduct -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +This project has adopted the [Microsoft Open Source Code of Conduct][02]. -Resources: +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and +healthy community. -- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) -- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) -- Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns -- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support) +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the + experience +- Focusing on what's best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +- Disruptive behavior + - Submitting spam comments, issues, or pull requests + - Defacing or vandalizing the project, repository, content, or documentation + - Intentionally introducing security vulnerabilities +- Disrespectful behavior + - Trolling, insulting or derogatory comments, and personal or political attacks + - Public or private harassment + - Publishing others' private information, such as a physical or email address, without their + explicit permission + - The use of sexualized language or imagery, and sexual attention or advances of any kind +- Other conduct that could reasonably be considered inappropriate in a professional setting + +## Resources + +- [Microsoft Open Source Code of Conduct][02] +- [Microsoft Code of Conduct FAQ][03] +- Contact [opencode@microsoft.com][04] with questions or concerns +- Employees can reach out at [aka.ms/opensource/moderation-support][01] + + +[01]: https://aka.ms/opensource/moderation-support +[02]: https://opensource.microsoft.com/codeofconduct/ +[03]: https://opensource.microsoft.com/codeofconduct/faq/ +[04]: mailto:opencode@microsoft.com diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc570ba2c7c2..88fc0a1d6e73 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,4 +3,4 @@ Thank you for your interest in contributing to quality documentations. As an open source project, we welcome input and updates from the community. -Please see our Contributor's Guide at https://aka.ms/PSDocsContributor. +Please see our Contributor's Guide at diff --git a/README.md b/README.md index 7ec7fb2c8871..4773a72a1a0d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ --- -ms.date: 11/02/2024 +ms.date: 01/03/2025 --- # PowerShell Documentation @@ -9,15 +9,6 @@ Welcome to the PowerShell-Docs repository, the home of the official PowerShell d This project has adopted the [Microsoft Open Source Code of Conduct][04]. -## Build Status - -[live-badge]: https://powershell.visualstudio.com/PowerShell-Docs/_apis/build/status/PowerShell-Docs-CI?branchName=live -[main-badge]: https://powershell.visualstudio.com/PowerShell-Docs/_apis/build/status/PowerShell-Docs-CI?branchName=main - -| live branch | main branch | -| :---------------------------- | :---------------------------- | -| [![live-badge][]][live-badge] | [![main-badge][]][main-badge] | - ## PowerShell Updatable Help (CabGen) CI Build Status [![Build Status][cabgen-status]][cabgen-log] @@ -29,14 +20,13 @@ This project has adopted the [Microsoft Open Source Code of Conduct][04]. The following list describes the main folders in this repository. +- `.devcontainer` - configuration files for the VS Code Remote - Containers extension - `.github` - contains configuration settings used by GitHub for this repository -- `.vscode` - contains configuration settings and recommended extensions for Visual Studio Code (VS - Code) +- `.vscode` - contains configuration settings and recommended extensions for VS Code - `assets` - contains downloadable files linked in the documentation - `redir` - contain redirection mapping files -- `reference` - contains the documentation published to - [learn.microsoft.com][01]. This includes both - reference and conceptual content. +- `reference` - contains the documentation published to [learn.microsoft.com][01]. This includes + both reference and conceptual content. - `5.1` - contains the cmdlet reference and about topics for PowerShell 5.1 - `7.4` - contains the cmdlet reference and about topics for PowerShell 7.4 - `7.5` - contains the cmdlet reference and about topics for PowerShell 7.5 @@ -52,9 +42,10 @@ The following list describes the main folders in this repository. - `tests` - contains the Pester tests used by the build system - `tools` - contains other tools used by the build system -> NOTE: The reference content (in the numbered folders) is used to create the webpages on the Docs -> site as well as the updateable help used by PowerShell. The articles in the `docs-conceptual` -> folder are only published to the Docs website. +> [!NOTE] +> The reference content (in the numbered folders) is used to create the webpages on the Docs site as +> well as the updateable help used by PowerShell. The articles in the `docs-conceptual` folder are +> only published to the Docs website. ## Contributing @@ -69,11 +60,13 @@ consistent across versions. ## Licenses -There are two license files for this project. The MIT License applies to the code contained in this -repo. The Creative Commons license applies to the documentation. +There are two license files for this project. The [MIT License][05] applies to the code contained in +this repo. The [Creative Commons license][06] applies to the documentation. [01]: https://learn.microsoft.com/powershell/scripting/ [02]: https://aka.ms/PSDocsContributor [03]: https://cla.microsoft.com/ [04]: CODE_OF_CONDUCT.md +[05]: LICENSE-CODE.md +[06]: LICENSE.md diff --git a/reference/docs-conceptual/community/contributing/get-started-writing.md b/reference/docs-conceptual/community/contributing/get-started-writing.md index b44d06839793..4fd2d09bbd6d 100644 --- a/reference/docs-conceptual/community/contributing/get-started-writing.md +++ b/reference/docs-conceptual/community/contributing/get-started-writing.md @@ -1,6 +1,6 @@ --- description: This article is an overview of how to get started as a contributor to the PowerShell documentation. -ms.date: 07/26/2022 +ms.date: 01/03/2025 title: Get started contributing to PowerShell documentation --- # Get started contributing to PowerShell documentation @@ -9,13 +9,16 @@ This article is an overview of how to get started as a contributor to the PowerS ## PowerShell-Docs structure -The [PowerShell-Docs repository][1] is divided into two groups of content: reference and -conceptual. +There are three categories of content in the [PowerShell-Docs][1] repository: + +- reference content +- conceptual content +- metadata and configuration files ### Reference content The reference content is the PowerShell cmdlet reference for the cmdlets that ship in PowerShell. -The cmdlet [reference][2] is collected in versioned folders (like 5.1, 7.0, and 7.2), which contain +The cmdlet [reference][2] is collected in versioned folders (like 5.1, 7.4, and 7.5), which contain reference for the modules that ship with PowerShell. This content is also used to create the help information displayed by the `Get-Help` cmdlet. @@ -28,6 +31,36 @@ version of PowerShell. > Anytime a conceptual article is added, removed, or renamed, the TOC must be updated and deleted or > renamed files must be redirected. +### Metadata files + +This project contains several types of metadata files. The metadata files control the behavior of +our build tools and the publishing system. Only PowerShell-Docs maintainers and approved +contributors are allowed to change these files. If you think that a meta file should be changed, +open an issue to discuss the needed changes. + +Meta files in the root of the repository + +- `.*` - configuration files in the root of the repository +- `*.md` - Project documentation in the root of the repository +- `*.yml` - Project documentation in the root of the repository +- `.devcontainer/*` - devcontainer configuration files +- `.github/**/*` - GitHub templates, actions, and other meta files +- `.vscode/**/*` - VS Code extension configurations +- `assets/*` - contains downloadable files linked in the documentation +- `redir/*` - contain redirection mapping files +- `tests/*` - test tools used by the build system +- `tools/*` - other tools used by the build system + +Meta files in the documentation set + +- `reference/**/*.json` - docset configuration files +- `reference/**/*.yml` - TOC and other structured content files +- `reference/bread/*` - breadcrumb navigation configuration +- `reference/includes/*` - markdown include files +- `reference/mapping/*` - version mapping configuration +- `reference/**/media/**` - image files used in documentation +- `reference/module/*` - Module Browser page configuration + ## Creating new articles A GitHub issue must be created for any new document you want to contribute. Check for existing