Skip to content

Latest commit

 

History

History
367 lines (264 loc) · 15.9 KB

CONTRIBUTING.md

File metadata and controls

367 lines (264 loc) · 15.9 KB
Raw

StoreBroker PowerShell Module

Contributing

Looking to help out? You've come to the right place. We'd love your help in making this the best submission solution for every Windows developer.

Looking for information on how to use this module? Head on over to README.md.

Table of Contents

Overview

We're excited that you're excited about this project, and would welcome your contributions to help it grow. There are many different ways that you can contribute:

  1. Submit a bug report.
  2. Verify existing fixes for bugs.
  3. Submit your own fixes for a bug. Before submitting, please make sure you have:
  1. Submit a feature request.
  2. Help answer questions.
  3. Write new test cases.
  4. Tell others about the project.
  5. Tell the developers how much you appreciate the product!

You might also read these two blog posts about contributing code:

Before submitting a feature or substantial code contribution, please discuss it with the StoreBroker team via Issues, and ensure it follows the product roadmap. Note that all code submissions will be rigorously reviewed by the StoreBroker Team. Only those that meet a high bar for both quality and roadmap fit will be merged into the source.

Maintainers

StoreBroker is maintained by:

As StoreBroker is a production dependency for Microsoft, we have a couple workflow restrictions:

  • Anyone with commit rights can merge Pull Requests provided that there is a 👍 from one of the members above.
  • Releases are performed by a member above so that we can ensure Microsoft internal processes remain up to date with the latest and that there are no regressions.

Feedback

All issue types are tracked on the project's Issues page.

In all cases, make sure to search the list of issues before opening a new one. Duplicate issues will be closed.

Bugs

For a great primer on how to submit a great bug report, we recommend that you read: Painless Bug Tracking.

To report a bug, please include as much information as possible, namely:

  • The version of the module (located in StoreBroker\StoreBroker.psd1)
  • Your OS version
  • Your version of PowerShell ($PSVersionTable.PSVersion)
  • As much information as possible to reproduce the problem.
  • If possible, logs from your execution of the task that exhibit the erroneous behavior
  • The behavior you expect to see

Please also mark your issue with the 'bug' label.

Suggestions

We welcome your suggestions for enhancements to the extension. To ensure that we can integrate your suggestions effectively, try to be as detailed as possible and include:

  • What you want to achieve / what is the problem that you want to address.
  • What is your approach for solving the problem.
  • If applicable, a user scenario of the feature / enhancement in action.

Please also mark your issue with the 'suggestion' label.

Questions

If you've read through all of the documentation, checked the Wiki, and the PowerShell help for the command you're using still isn't enough, then please open an issue with the question label and include:

  • What you want to achieve / what is the problem that you want to address.
  • What have you tried so far.

Static Analysis

This project leverages the PSScriptAnalyzer PowerShell module for static analysis.

It is expected that this module shall remain "clean" from the perspective of that module.

To run the module, from the root of your enlistment simply call

    Invoke-ScriptAnalyzer -Path .\ -Recurse

That should return with no output. If you see any output when calling that command, either fix the issues that it calls out, or add a [Diagnostics.CodeAnalysis.SuppressMessageAttribute()] with a justification explaining why it's ok to suppress that rule within that part of the script. Refer to the PSScriptAnalyzer documentation for more information on how to use that attribute, or look at other existing examples within this module.

Please ensure that your installation of PSScriptAnalyzer is up-to-date by running: Update-Module -Name PSScriptAnalyzer You should close and re-open your console window if the module was updated as a result of running that command.

Visual Studio

A Visual Studio project exists for this module:

StoreBroker.pssproj

Even if you don't use Visual Studio to edit this module, others do, so if you add new files to the module, be sure that the VS project is updated as well.

To open this project in Visual Studio, you need to have the free PowerShell Tools For Visual Studio extension installed.

Module Manifest

This is a manifested PowerShell module, and the manifest can be found here:

StoreBroker\StoreBroker.psd1

If you add any new modules/files to this module, be sure to update the manifest as well. New modules should be added to NestedModules, and any new functions or aliases that should be exported need to be added to the corresponding FunctionsToExport or AliasesToExport section.

Logging

Instead of using the built-in Write-* methods (Write-Host, Write-Warning, etc...), please use

Write-Log

which is implemented in Helpers.ps1. It will take care of formatting your content in a consistent manner, as well ensure that the content is logged to a file (if configured to do so by the user).

PowerShell Version

This module must be able to run on PowerShell version 4. It is permitted to add functionality that requires a higher version of PowerShell, but only if there is a fallback implementation that accomplishes the same thing in a PowerShell version 4 compatible way, and the path choice is controlled by a PowerShell version check.

For an example of this, see Write-Log in Helpers.ps1 which uses Write-Information for Informational messages on v5+ and falls back to Write-Host for earlier versions:

if ($PSVersionTable.PSVersion.Major -ge 5)
{
    Write-Information $ConsoleMessage -InformationAction Continue
}
else
{
    Write-Host $ConsoleMessage
}

Coding Guidelines

As a general rule, our coding convention is to follow the style of the surrounding code. Avoid reformatting any code when submitting a PR as it obscures the functional changes of your change.

A basic rule of formatting is to use "Visual Studio defaults". Here are some general guidelines

  • No tabs, indent 4 spaces.
  • Braces usually go on their own line, with the exception of single line statements that are properly indented.
  • Use camelCase for instance fields, PascalCase for function and parameter names
  • Avoid the creation of script or global scoped variables unless absolutely necessary. If referencing a script or global scope variable, be sure to explicitly reference it by scope.
  • Avoid more than one blank empty line.
  • Always use a blank line following a closing bracket } unless the next line itself is a closing bracket.
  • Add full Comment Based Help for all methods added, whether internal-only or external. The act of writing this documentation may help you better design your function.
  • File encoding should be ASCII (preferred) or UTF8 (with BOM) if absolutely necessary.
  • We try to adhere to the PoshCode Best Practices and DSCResources Style Guidelines and think that you should too.
  • We try to limit lines to 100 characters to limit the amount of horizontal scrolling needed when reviewing/maintaining code. There are of course exceptions, but this is generally an enforced preference. The Visual Studio Productivity Power Tools extension has a "Column Guides" feature that makes it easy to add a Guideline in column 100 to make it really obvious when coding.

Code comments

It's strongly encouraged to add comments when you are making changes to the code and tests, especially when the changes are not trivial or may raise confusion. Make sure the added comments are accurate and easy to understand. Good code comments should improve readability of the code, and make it much more maintainable.

That being said, some of the best code you can write is self-commenting. By refactoring your code into small, well-named functions that concisely describe their purpose, it's possible to write code that reads clearly while requiring minimal comments to understand what it's doing.

Testing

This module supports testing using the Pester UT framework.

If you do not have Pester, download it here. Create a Pester folder under any path in $env:PSModulePath. Unzip the contents of the download to the Pester folder. Pester should now automatically import whenever you run a function from its module.

In the StoreBroker module, the source tree and test tree are children of the project root path. Working code should be placed under $root\StoreBroker. Tests should be placed under $root\Tests. Each file in the Tests folder should test one file in the StoreBroker folder. For example, the file $root\StoreBroker\PackageTool.ps1 should have a corresponding file $root\Tests\PackageTool.Tests.ps1. As the example shows, the filename of the test file indicates which file from the source tree it is testing.

Tests can be run either from the project root directory or from the Tests subfolder. Navigate to the correct folder and simply run Invoke-Pester.

Pester can also be used to test code-coverage, like so:

Invoke-Pester -CodeCoverage "$root\StoreBroker\PackageTool.ps1" -TestName "*PackageTool*"

This command tells Pester to check the PackageTool.ps1 file for code-coverage. The -TestName parameter tells Pester to run any Describe blocks with a Name like "*PackageTool*".

The code-coverage object can be captured and interacted with, like so:

$cc = (Invoke-Pester -CodeCoverage "$root\StoreBroker\PackageTool.ps1" -TestName "*PackageTool*" -PassThru -Quiet).CodeCoverage

There are many more nuances to code-coverage, see its documentation for more details.

Releasing

If you are a maintainer:

Ensure that the version number of the module is updated with every pull request that is being accepted.

This project follows semantic versioning in the following way:

<major>.<minor>.<patch>

Where:

  • <major> - Changes only with significant updates.
  • <minor> - If this is a feature update, increment by one and be sure to reset <patch> to 0.
  • <patch> - If this is a bug fix, leave <minor> alone and increment this by one.

When new code changes are checked in to the repo, a new NuGet package must be published by Microsoft. This process is documented in Microsoft's internal StoreBroker repo. Refer to the CONTRIBUTING.md in that repo for more information on creating a signed NuGet package.

Once the new version has been pulled into master, there are two additional tasks to perform:

  • Update CHANGELOG.md
  • Add a tag for that version to the repo

Updating the CHANGELOG

To update CHANGELOG.md, just duplicate the previous section and update it to be relevant for the new release. Be sure to update all of the sections:

  • The version number
  • The SB tree (we'll get that path working in a moment)
  • The release date
  • A brief list of all the changes (use a - for the bullet point if it's fixing a bug, or a + for a feature)
  • The link to the pull request (pr) (so that the discussion on the change can be easily reviewed) and the changelist (cl)
  • The author (and a link to their profile)
  • If it's a new contributor, also add them to the Contributors list below.

Then get a new pull request out for that change to CHANGELOG.

Adding a New Tag

To add a new tag:

  1. Make sure that you're in a clone of the actual repo and not your own private fork.
  2. Make sure that you have checked out master and that it's fully up-to-date
  3. Run `git tag -a ''
  4. In the pop-up editor, give a one-line summary of the change (that you possibly already wrote for the CHANGELOG)
  5. Save and close the editor
  6. Run git push --tags to upload the new tag you just created

If you want to make sure you get these tags on any other forks/clients, you can run git fetch origin --tags or git fetch upstream --tags, or whatever you've named the source to be.

Contributors

Thank you to all of our contributors, no matter how big or small the contribution:

Legal and Licensing

StoreBroker is licensed under the MIT license.

You will need to complete a Contributor License Agreement (CLA) for any code submissions. Briefly, this agreement testifies that you are granting us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright. You only need to do this once.

When you submit a pull request, @msftclas will automatically determine whether you need to sign a CLA, comment on the PR and label it appropriately. If you do need to sign a CLA, please visit https://cla.microsoft.com and follow the steps.