VMworld Hackathon 2019 – PowerCLI team

The annual VMworld Hackathon hosted by the VMwareCode team is one of my favorite events of the year. We get to hang out with community members, eat, drink and pound on keyboards in a competition where anything goes. I’ve participated in each of the last 4 events (US only), and for the first time I was on the winning team! Very exciting! Thank you to the VMwareCode team for continuing to support such a fun event for the community! It’s honestly less about competing and more about learning new things. One of the best parts is getting messages weeks later stating that I helped someone with some little keyboard trick.

This year I put together a team and had a whole bunch of folks join to have some fun with the PowerCLI examples repository. The team was comprised of folks who had skills that ranged from novice to expert. Hopefully everyone learned a few things and could apply them to their normal jobs.

Huge thanks to all my team members. You guys were AWESOME & fun to work with!!

This Year’s Project:

The team would focus on creating an automated process around the PowerCLI Examples repository in GitHub. Some tasks would include:

• Authoring a Build pipeline
  • Using AppVeyor platform
• Creating quality gates for deployment
  • Using PSScriptAnalyzer for Linting rules
  • Pester for Unit tests
• Advanced Tasks
  • Resolve any current Lint Errors (There are Hundreds)
  • Implement auto-fix instructions during commits for common errors
  • Add Pester Tests for scripts

Why would this be a useful project?

The PowerCLI examples repository is simply a mess. A lot of folks have submitted useful scripts/examples/modules and other things to the repository but there is no consistency in the material. It’s unrealistic to think that one person or even a small group could provide the oversight needed on such a large repository to ensure that only quality/useful code was being published. Our Hackathon team focused on attempting to make this process a little more human friendly. Which would allow the repository owners to set up acceptance criteria and allow for the build process to determine if the code meets the requirements. Additionally it would be great for the consumer of the repository to have an easy method for downloading and using the PowerCLI examples.

What we decided on:

In talks with the team we adjusted the tasks for the night to focus on making the PowerCLI examples repository more user friendly from the Administrative and User side. This would include the following tasks for the night:

• Create a new GitHub Repository to keep things clean
• Only focus on the Scripts Directory
• Convert all the Scripts to Functions
• Package the Functions as a PowerShell Module
• Scaffold a directory structure to support a PowerShell Module
• Select a single Script, convert it to a function
  • Add Pester Tests for the Single script
• Create CI/CD pipeline using AppVeyor
• Publish new Module to the PowerShell Gallery
• Review/Define quality gates
• Run Linting tools against the newly created functions

What we accomplished:

The good news is that we were able to complete each of the tasks above, with only a few caveats.

• All of the scripts were converted to functions and the Linting was run against them. However it would not make sense to blindly place all of these items in the Module.
  • The repository we worked from can be viewed on my GitHub page.
• Only 1 function Get-MigrationsSet has unit tests, it would take some time to create the tests for all of the functions that were converted. See the first bullet.
  • View the Pull Request for details
  • Latest AppVeyor Build
  • View it on the PowerShell Gallery

How’s it work?

1. The contributor 
   1. Forks the repository
   2. Creates a new Branch for their function
   3. Adds a Function file and appropriate test file
   4. Adds the appropriate Function and test code
      1. Can run tests locally 
   5. Commits code to their Branch and Fork
   6. Creates a Pull Request (PR) to the Master repository
2. The Repository owner
   1. Reviews the Pull Request
      1. AppVeyor Results
      2. General code purpose
      3. Suggests any edits
   2. Approves or denies the PR
      1. If the PR is approved
         1. The Module is updated on the PowerShell Gallery
            1. Requires a string added to the Merge ‘!deploy’
3. The Consumer
   1. Can Install the module from the PowerShell Gallery
      1. ‘Install-Module PowerCLIExamples‘
   2. Can Update the module from the PowerShell Gallery
      1. ‘Update-Module PowerCLIExamples‘

What does the future hold?

Here are my suggestions for the ‘PowerCLI Examples Repository’ of the future….

• Repository Ownership
  • It’s unclear the level of ownership that VMware should take for the repository and for the module(s). 
  • This comes down to legal responsibility and I cannot speak to what the outcome should or will be.
• Modules
  • All of the current modules in the Module directory should be broken out into their own repositories. See first bullet.
  • All modules should still follow best practices outlined for the Module Quality gates that need to still be finalized
• Scripts
  • All Scripts should be reviewed to determine if they are better suited as functions.
  • Scripts are okay, but are less user friendly as far as a Module goes.
  • Should still follow best practices outlined for the Module Quality gates that still need to be finalized
• Functions
  • All functions should be reviewed to ensure they make sense. Are generally useful and not duplicated.
  • Should still follow best practices outlined for the Module Quality gates that still need to be finalized
• Module Quality Gates
  • These need to be developed over time
    • Start small, Iterate often, Automate always
  • They will help every contributor write better code
  • Should not be overly complex for new contributors
    • Yes, there is still a learning curve