Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (98 loc) · 6.1 KB

CONTRIBUTING.md

File metadata and controls

132 lines (98 loc) · 6.1 KB

Contributing to PSGSuite

Thank you for your interest in helping PSGSuite grow! Below you'll find some guidelines around developing additional features and squashing bugs, including some how-to's to get started quick, general style guidelines, etc.

Git and Pull requests

  • Contributions are submitted, reviewed, and accepted through GitHub Pull Requests:
    • Learn more about it here.
  • We follow the *Fork and Pull- model.
    • Learn more about it here.
  • When submitting a pull request, ensure the Allow edits from maintainers option is checked. This allows maintainers to make necessary edits directly to your branch and include them in the same pull request.
    • Learn more about it here.

Overview

Here's the overall flow of making contributions:

  1. Fork the repo
  2. Make your edits / additions on your fork
  3. Push your changes back to your fork on GitHub
  4. Submit a pull request
  5. Pull request is reviewed. Any necessary edits / suggestions will be made
  6. Once changes are approved, the pull request is merged into the origin's main branch and deployed to the PowerShell Gallery once CI tests pass

Code Guidelines

Please follow these guidelines for any content being added:

  • ALL functions must...

    • Work in the supported PowerShell versions by this module
    • Work in any OS;
      • Any code that includes paths must build the path using OS-agnostic methods, i.e. by using Resolve-Path, Join-Path and Split-Path
      • Paths also need to use correct casing, as some OS's are case-sensitive in terms of paths

  • Public functions must...

    • Include comment-based help (this is used to drive the Wiki updates on deployment)
    • Include Write-Verbose calls to describe what the function is doing (CI tests will fail the build if any don't)
    • Be placed in the correct APU/use-case folder in the Public sub-directory of the module path (if it's a new API/use-case, create the new folder as well)
    • Use SupportsShouldProcess if...
      • The function's verb is Remove or Set.
      • It can be included on Update functions as well, if felt that the actions executed by the function should be guarded
      • Get functions should never need SupportsShouldProcess

  • Every Pull Request must...

    [!NOTE] These can be added in during the pull request review process, but are nice to have if possible

    • Have the module version bumped appropriately in the manifest (Major for any large updates, Minor for any new functionality, Patch for any hotfixes)
    • Have an entry in the Changelog describing what was added, updated and/or fixed with this version number

      [!NOTE] Please follow the same format already present

    • Have an entry in the readme's Most recent changes section describing what was added, updated and/or fixed with this version number

      [!NOTE] Please follow the same format already present

      This can be copied over from the Changelog entry

Documentation Guidelines

The PSGSuite documentation site is built using MkDocs. Follow these steps to spin up MkDocs locally, make changes, and preview your updates before submitting them.

Requirements

  • Python (version 3.7 or higher):
    • Download and install Python from python.org.
    • Ensure pip (Python's package manager) is installed and available in your PATH.
  • MkDocs and Dependencies:
    • Install MkDocs and its dependencies using the provided requirements.txt file.

Setting up MkDocs Locally

  • Fork the PSGSuite repository
  • Clone your forked repository to your local machine
git clone https://github.com/<your-username>/PSGSuite.git
  • Navigate to the cloned repository directory
cd //path/to/PSGSuite
  1. Install dependencies
pip install -r requirements.txt
  1. Start the MkDocs development server and navigate to http://127.0.0.1:8000 in your web browser
mkdocs serve
  1. Make your edits and submit a pull request

Note

The Function Help content is automatically updated during the deployment builds. Any new or updated comment-based help will be transformed to Markdown using platyPS and pushed when deployment conditions are met. Install MkDocs and its dependencies using the provided requirements.txt file.

Getting Started

Enabling Debug Mode

Warning

TODO: Add instructions for how to use build.ps1 to enable debug mode for the module.

Google .NET SDK Documentation

PSGSuite uses Google's .NET SDK's for 99% of its functions. The easiest way to pull up the documentation for the function you are writing is by visiting Google's API .NET GitHub repository. Scroll down to API-specific Libraries for more .NET SDK Documentation and API documentation.

Keeping in Touch

For any questions, comments or concerns outside of opening an issue, please reach out: