PowerShell Working Groups

Joey Aiello

Joey

Since we open sourced PowerShell in 2016, PowerShell has been an immensely popular project on GitHub. Every year, 700-1000 PRs and 1300-1500 issues are submitted to the PowerShell repo, with roughly half of the PRs and 90% of the issues filed from the community.

We realize that some of these issues and PRs have been piling up and, as the project has grown in popularity and community activity, we sometimes struggle with the sheer volume of them. Those of us on the PowerShell Committee have been discussing some ways that we think we might be able to improve the efficiency of our decision-making process, and to reduce bottlenecks that may be causing the increase in our overall backlog.

We set out with a couple of goals:

First, we wanted to increase the velocity of innovation in PowerShell, but without compromising the stability of the engine and language that so many depend upon within their critical infrastructure and automation environments. It’s critical that anything we do in changing the management of the PowerShell project not jeopardize this.

We also noticed that a lot of contributor time is being spent on contributions and discussions that are ultimately rejected by Maintainers or the Committee. Despite being rejected for legitimate reasons (e.g. risky breaking changes), we recognize that the rejection could happen before the contributor spends considerable time and effort.

To that end, we want to:

  1. increase the number of people who can make approve or reject proposals, especially where those people have domain-specific knowledge about a topic
  2. make those approvals and rejections more explicit, giving contributors confidence in moving forward
  3. make approvals and rejections earlier in the process to avoid unnecessary work for contributors and maintainers

Working Groups

To meet these goals, we are introducing the concept of Working Groups (WGs) within the PowerShell project (including those repositories that contribute their modules into the PowerShell package). You can think of WGs as subcommittees for specific areas within the PowerShell project. Some of their responsibilities include:

  1. Fostering discussions in issues and pull requests
  2. Deciding whether feature proposals need request-for-comment (RFC) docs to be approved by the Committee
  3. Approving or rejecting feature proposals in issues
  4. Offering guidance and expertise in RFC discussions
  5. Triaging bugs filed as issues
  6. Reviewing code in pull requests

Initially, working groups will only consist of PowerShell Team members, but we will be reaching out to high-impact community contributors over the next few months to gauge their interest in joining WGs.

Issue Flow

There are two primary categories of issues that get filed in the PowerShell repository: bugs and feature proposals. Bugs and features will each be handled differently going forward.

Bugs

Bugs are the easy case. At a high-level, when a bug gets filed:

  1. A Maintainer will label the issue with the appropriate Working Group(s)
  2. Working Group members for those labels will review the bug to determine if it is a legitimate bug, by-design, external to the project, and/or worth spending time to fix (based on the value, complexity, risk, etc.)
  3. When a bug has been established as legitimate, Working Group members will establish the severity of the bug (i.e. the importance of fixing it)
  4. If and when a PowerShell Team member or contributor files a PR to fix the bug, at least one Working Group member will be responsible for reviewing the PR.

In practice, this is similar to how bugs are already handled today. However, we’re hopeful that the addition of Working Group members outside of the PowerShell Team will enable a greater number of bugs to be triaged and resolved appropriately, as well as to unblock a number of bug fixes in PR that are of a lower priority.

Feature Proposals

Feature proposals are a little more complicated.

First and foremost, any new feature proposals should initially be filed as issues, specifically using the issue template for feature requests (subject to some ongoing changes). This issue must include:

  • a description of the feature being proposed
  • the scenario for using the feature (i.e. why is the feature useful in the real world)
  • examples of how the feature might work in practice (including mandatory example script blocks and output)

Again, Maintainers will label the issue for the appropriate WGs in order to bring them into the issue for discussion. Working Group members will facilitate a discussion with the community around the utility and design of the proposal, as well as contributing their expertise on the feasibility and design consistency of implementing the proposal.

One pattern that we are noticing within the PowerShell repo today is the large number of proposals that could be implemented outside of PowerShell itself (usually via external modules). In keeping with our goal of maintaining stability in PowerShell, we’d prefer that this experimentation happens via the PowerShell Gallery, where modules can be published as prerelease, and where semantic versioning can be used to communicate breaking changes. Therefore, WGs will aggressively reject any feature proposals that can be implemented externally from the repo.

WGs will also decide whether they believe the feature proposal requires an RFC, based on the complexity, size, and potential impact of the proposal. Where RFCs are not required, WGs will approve the proposal and then will review the eventual PR to implement it. Where RFCs are required, contributors will be asked to submit RFCs. Working Group members will participate heavily in the RFC discussion, contributing their expertise to help the Committee make decisions on whether to accept the proposal.

Experimental Features

Experimental features are features shipped in PowerShell that are not officially supported as they may be unstable or subject to change in the future. (They’re turned on by default in preview branches and off by default in officially supported versions, including release candidates.)

We introduced experimental features as a way to accelerate development and gather feedback in situations where we’re unsure whether a specific approach is best, and where we may want to change the behavior before users start depending on it in production.

In the past, we’ve largely used experimental features for new behavior that we already have a strong intent to eventually merge. While we’ve caught certain issues that have prevented experimental features from being accepted as stable, we believe the current perception is that these features will eventually become stable.

In the future, we’d like to use experimental features for experimenting and gathering user feedback on whether a feature should exist at all, with a more explicit assertion that many of them will never find their way to a supported GA release. This means that we may be accepting more PRs into PowerShell as experimental features, but that this acceptance is not necessarily long-term acceptance into PowerShell.

Instead, the RFC process will be used to convey full acceptance, something that may happen long after code has been accepted as experimental. And in fact, the feedback received around the experimental will be used by the Committee to inform the RFC decision.

What’s next?

Similar to the way we roll out functionality in PowerShell, we’ll be taking a staged approach to rolling out these governance changes, taking feedback along the way.

In the near term, members of the PowerShell Team have been added to preliminary WGs, and you’ll see Area issue labels change to reflect these WGs as we’ve defined them. Members of these WGs will be responsible for triaging new issues under those labels, reviewing PRs under those labels, and (eventually) working through the backlog of existing issues. WGs will also be experimenting with various ways of organizing themselves, including how they divvy up issues/PRs and how much consensus amongst themselves to make a decision.

Over the next couple months, we’ll introduce more of this process as official governance proposals within the RFC repo, and update our existing governance language to reflect the new changes. These changes may continue to evolve as we learn more about what does and doesn’t work.

The Committee will address existing RFCs on a case-by-case basis. Some have already been extensively discussed as issues and/or RFC discussions, and we may choose to move forward with experimental implementations or reject them altogether.

If folks feel that issues, pull requests, or RFCs aren’t being adequately addressed by WGs, they should still feel free to mention @PowerShell/powershell-committee or to request that a Review-Committee label be added. In the future, we’ll have more guidance on how escalations and Committee reviews will work.

Eventually, we’ll reach out to contributors who may be interested in joining these Working Groups, completing our original goal of increasing the number of people who can make decisions about specific areas of PowerShell.

Thank you!

Thanks to our contributors and users for continuing to submit issues, pull requests, and RFCs to the PowerShell repo. We appreicate your patience as we work towards this new model, and we encourage you to provide feedback as issues in the PowerShell-RFC repo as we continue on this journey.

6 comments

Leave a comment

  • Avatar
    Michael Taylor

    The blog title is not appearing on either the (DevBlogs)[https://devblogs.microsoft.com/] or Powershell blog making it impossible to get to here without clicking on the comment link first.

    The title is empty with the author and date time below it.

  • Michael Mientus
    Michael Mientus

    This post makes it sound like the PowerShell team will be discouraging ideas and coding. I think it should be clear to contributors that not every contribution will meet the goals of the project. And there are plenty of ways to extend PowerShell or to use it in private projects that don’t depend on changing the PowerShell source. I don’t know if the following exists, but there should be a project mission statement and a short list of coding options (modules, targeting PowerShell) that can be referred to. I know that the PowerShell Gallery, modules, NuGet SDKs, etc exist. That might not be true for everyone filing issues on GitHub. Ultimately, they might decide those options aren’t for them. I don’t feel like they should come away thinking their ideas are bad or that being punted from the source code means there is no way to do what they want.

    • Joey Aiello
      Joey AielloMicrosoft employee

      I totally understand your concerns here, Michael. It’s a very difficult line to tread: namely, that we *do* want to raise the bar slightly for the kinds of contributions being made to PowerShell itself, but without squashing innovation and collaboration across the ecosystem.

      We do plan to update our CONTRIBUTING.md, issue/PR templates, and other governance docs over time to guide people to the appropriate place to push for this innovation (which admittedly, may still be in PS/PS depending on what it is). However, we wanted to take a more piecemeal approach to moving towards this new model so we could collect feedback along the way and avoid confusing people without proper context.

  • Avatar
    ILYA Sazonov

    Since MSFT announced huge development plans for 7.2 milestone it would be nice to start a preparation of PowerShell repository early (today?). We have over 2600 issues and over 90 PRs and we need many time to re-classify them with new WG labels. Do you consider to train a GitHub bot?