Written by Joel Sallow
I was never really looking to get into software development, at least in the beginning, but I was always interested in technology and computers. Growing up I picked up a really old QuickBASIC book and tinkered around for a while, but it never really led anywhere. A while later on I’d tinker with modding a few video games here and there. I wrote a mod for Spore for a handful of months, and I was always at least a little curious in tinkering with web design. In 2016 I moved to Florida to meet my now-wife, and needed to work somewhere. Having been pretty disillusioned with college and university even before I left Australia, I hadn’t made it very far in that regard, so my options there were limited.
I worked at a couple places before getting a job as low-level tech support for a flooring company. They had… a lot of tech problems. People problems too; those seem to go hand in hand quite a lot.
For a while I just helped out where I could, but the lack of a mature IT department eventually forced me to look around for tools I could use to make the job easier. PowerShell happened to come in the box, which was very convenient; most of these systems were Windows 10 or being replaced with Windows 10 as they fell apart, primarily workstations.
Eventually I stumbled on the /r/PowerShell subreddit and started picking up what I could, helping folks out where I was able. After a while, I found the Discord/Slack channels and stayed plugged in. I don’t really remember how long it took, but after a while you start to recognise the common questions that come up, which is what motivated me to create PSKoans. After all, why answer the same question over and over when I can just point to something I built which explains it better than I can after the 20th time that day?
Creating PowerShell Koans
PowerShell Koans are a series of Pester tests with extensive comments that are designed to illustrate how PowerShell features work, including a lot of the lesser-known edge case details that tend to trip folks up. It’s packaged up as a module to help newer folks make sense of the somewhat confusing display of errors at times. Feel free to download it from the PowerShell Gallery and give it a look!
# The first step's only needed for Windows PowerShell users (v5.1)
Install-Module Pester -Force -SkipPublisherCheck -MaximumVersion 4.99.99
Install-Module PSKoans
Show-Karma
Developing PowerShell Koans was an investment; I can’t be everywhere and help everyone I might want to, so I built something that is suitably well-equipped for people to be able to help themselves.
I utilise Pester to write the koans in a way that (hopefully) makes a decent amount of sense to newer folks and experienced folks alike; Pester’s base syntax for tests and assertions lends itself very well to explaining as you go, and any gaps are filled in with pretty extensive comments in the code. They’re written as a series of Pester test files, and you have the module commands there to prompt you when you get lost or want to check your answers.
The Show-Karma command will have the module invoke Pester to check your progress and report back, with some pretty console formatting and some additional flavour-text because the bare Pester output can be a bit daunting, especially if you’re not used to it.
In this way you can take it at your own pace, checking in with Show-Karma whenever you need to verify your answers and/or get pointers on which section to attack next. If you prefer, Show-Karma also takes a -Topic parameter so you can just jump directly to the topic(s) you’re interested in. You can also tab-complete topic names, so you needn’t worry about remembering any of them.
After some months tinkering away at that and poking at other projects, a few people encouraged me to contribute to PowerShell itself. It was a new language for me, though with familiar roots, and I had a little bit of prior experience with C# from my brief time in university. It took… about a month to finish that first pull request, although including a lengthy (but very necessary) review process it ended up taking about 3-5 months. Definitely not the typical case, as I was trying to change some fundamentals in the parsing engine to add some more number types (see this docs page that I helped write to explain the vast extent of the feature). I have a habit of diving in the deep end, I suppose.
Many PRs later, I’ve picked up quite a lot during this process, and working on new PRs has become my primary way of learning new concepts. I’ll often seek out help from more knowledgeable folks in the community when I’m working out of my depth, and there has been a lot I’ve learned that way too. After a while, some friends and I put together a portfolio site to see if I could get a better job. A few folks reached out, but eventually I ended up in my current job at Chocolatey Software.
Going Open Source
Initially the only things I put on Github were a loose collection of scripts, some things I found useful for work, and examples I’d written to answer a question on Reddit or the community Discord channels. So a few odds and ends, as well as a little bit of Git experience. I also knew I’d have trouble keeping track of everything I wanted to incorporate into PSKoans unless I had some kind of version history, so it was a good fit to get it on Github. Plenty of folks knew the platform well, so I had people around to ask if I ever got lost.
It also served as an open invitation as an open source project; if anything’s lacking, people are more than welcome to file issues or just outright write their own set of koans and we’ll do some code review and help incorporate them where they fit best. That was a pretty big appeal; writing a project solo is always daunting, and the PowerShell community is always happy to lend a hand, especially if your intent is to give back to that community.
Getting started is always a challenge. I think I had only a handful of topics I wanted to cover to begin with. It was, and is, ongoing work to expand that to cover as much as possible. Designing the framework around it was also quite challenging; since PSKoans needs to utilise Pester and also relies somewhat on interactive console sessions, I had to do some work to decouple it from the usual console session, so that it wouldn’t (seemingly) randomly fail when you restart the console session and (for example) some module you had used last time that isn’t loaded yet.
That took some months to sort out properly, and I’ve had to revisit it recently with some of the changes that came with the recently released Pester v5. I have most of that code all sorted out, but as it happens, trying to test code in Pester that’s running Pester itself is a bit of a tricky proposition at best!
Currently I’m working on the Advanced Functions topic and attempting to cover that thoroughly. There’s lots of parameter binding and fun things to cover, as well as some of the less-used bits and pieces that come with it. I’m also working on ensuring the module works correctly with v5 of Pester. I’m thinking I’ll probably do one more release in Pester v4, and then move things along and finish the move to Pester v5. Thankfully, very few of the koan topics themselves need to be altered for Pester v5 to work, it’s mainly module functionality that has to be adjusted for the new result formats and taking advantage of Pester’s discovery features properly.
The importance of open source software
In my opinion, open source software is critical. You can only learn so much in a closed space. If your code isn’t open to critique, you won’t write it nearly as well, and it’s also harder to seek help when you need it if you’re not in a position to actually share the code. It also gives others a chance to learn from you, as well as help you learn.
Being able to learn from open source projects is also hugely valuable; you can see how others have solved real-world problems, which is massively more valuable than trying to learn from a theoretical or contrived scenario.
It’s a good guard against getting too accustomed to a single code style or methodology as well; if all you ever write is code for your workplace you tend to adopt the common habits, both good and bad. Having some awareness of the wider community and how different people code makes it easier to drop and refactor out the bad patterns and keep the good ones.
My advice when it comes to open source? Get started. Throw your code on Github or wherever you want, there’s a few options out there. But include documentation! That doesn’t necessarily mean documentation for the code itself, it might not be at that stage yet, and that’s OK! But you should be including documentation for your projects so that others in the community know how they can interact with it. That means:
- A proper license, so folks know if you’re okay with them deriving your work.
- A contributing document explaining what processes you’d like to use for issues, feature requests, pull requests, etc.
- A basic issue template, so people know what information you need to be able to address any concerns/problems they may have. These can get pretty detailed, and you can have multiple types, but if you’re just getting started at least include a basic one.
- If/When you have a public version release, especially if you’re distributing it on another platform (for example, as a package on some other service like the PowerShell Gallery), include notes on how that’s actually done, so that if you ever want someone else to take over, they can.
Feel free to look at other open source projects for inspiration for those as well! You may not need all the detail embedded in the project documentation of a mature project, but you really should include some. Without any of that, people who may want to help out will have a really hard time figuring out how you want them to help! Remember that open source projects can and often do have multiple owners and maintainers. Part of enabling that is ensuring you have decent documentation for the processes you want to use in your repo. If you’re not sure yet, it’s OK to leave some things out, but don’t leave people guessing on the day to day things!
More from the author
I’m Joel Sallow, and I’m currently a software engineer at Chocolatey Software. You’ll often find me around the PowerShell Slack and Discord channels, but you can also follow me on Twitter or Github, and you can keep tabs on my blog that I’ll post to once in a while if I find something interesting and feel the need to write about it!
-=-
If you’d like to know more about Microsoft and open source, you can find more stories and info here.
Top comments (0)