This holiday season I decided to embark on a challenge of committing things back to the open source community. There already is the well-established Advent of Code; however, I struggle with participating as development isn’t something, I do day in and day out. I still wanted to participate and challenge myself during this holiday season and decided the best outlet for me was to contribute back to the open source community with things I have learned or taking the initiative and correcting inaccuracies in documentation.

Getting Started

The first challenge was where to start, which to be honest was easier than I imagined. Lately I’ve been playing with Azure Bicep and if you’ve read my blog then you may know I already have quite a couple posts on bicep, Translating An Azure Quickstart to Bicep and Walkthrough of Working with Bicep Modules.

The twist I decided was to elaborate on the Translating An Azure Quickstart to Bicep post and look for any Azure Quickstart Templates that might be outdated AND not yet a bicep example.

For those unfamiliar the azure quickstart templates is an open source project where contributors can submit Azure Resource Manager (ARM) templates for building and configuring Azure resources. However; a downside to this project is templates can become outdated as new features and Azure APIs are updated.

So, the first one I found that fit this bill was the 101-cosmosdb-free quickstart example. This one required the apiVersions to be updated:

So did a quick PR and updated the APIs as well as necessary metadata changes to reflect the last updated date and submitted it back.

Once that was done then the next step was to create a bicep example for a cosmosdb-free tier. This also helped reenforce my learnings on the bicep language.

Updating Contribution Guidelines

In addition, while doing these updates noticed that the contribution guidelines on the bicep project and the azure-quickstart project could be updated to better clarify a few things.

For those unfamiliar the contribution guidelines help point contributors as to what the projects best practices are and how to best update and maintain the project. Well, this led to two more PRs for these changes.

For Azure Quickstarts it was getting feedback that a PR should only reference one template. This wasn’t in the contribution guideline so a quick change fixed this. For bicep it was realizing the examples were not alphabetically listed and updating the contribution guideline to guide those who may follow after.

YAML Pipeline Documentation

Another topic I have been working with a lot lately is the use of YAML Pipelines to handle build and deployments. Here just some of the topics:

• Multi-Stage YAML Pipelines in a Microservice Architecture
• Introduction to MultiStage YAML Pipelines
• What To Do when YAML Pipelines Fail
• YAML Pipelines: New Deployment Architecture
• YAML Pipelines: Manual Validation Task

Well uncovering and working with all the associated Microsoft documentation one would be surprised at how the documentations terminology might be out of date or incomplete. One pet peeve of mine that is especially true when it came to working with YAML Pipelines is that a lot of Microsoft’s documentation referred to ‘Pipelines’ and ‘Releases’ but all the pictures and description was actually ‘Classic Pipeline’ and ‘Classic Releases’. This is understandable since the terminology has recently change.

This is something that could be really frustrating to those just starting out with using YAML Pipelines. So, I took it upon myself to make updates to the terminology where needed to help those that may follow.

Also, after working these Pipelines you realize there is some clarity that can be added to help those that come after. An example of this is when dealing with MultiStage YAML deployments the documentation wasn’t clear that if defining a dependsOn section it will remove the default assumption that the previous stage succeeded. This can be frustrating and not entirely noticeable unless a previous stage fails and the subsequent one still runs. This was another one I was able to take upon myself to add the clarity and commit it back.

My Own Lessons Learned

It wasn’t easy. Trying to motivate myself to do a Pull Request a day. I didn’t make it every day but made up for the days I missed. Reflecting back, it made me get better at forking repositories appropriately, adding clarifying details, and be more critical when reviewing existing documentation.

It also led me to further my knowledge on certain topics like Azure Bicep and then also updating my existing Azure skillset by seeing what new functionality was available when upgrading the Azure APIs for Azure Quickstarts.