We all want our Open Source projects to be clear and simple to contribute to and we may think that they are. Sure, making contributions to our project looks simple to us, but we are the ones who wrote the code and know all its bits and bytes. How can we be confident that our code is readable and easy to contribute to?
One idea that worked for us at CyberArk is utilizing members of other CyberArk teams to validate our OSS experience. Recently, the Secretless Broker team worked on improving their codebase to make it easier for the community to make contributions and add Connector Plugins to the product. The Secretless Broker team wanted early feedback on their community contribution process and invited me to implement a new Connector for their project as if I was a community user. I am the perfect candidate because, although I am familiar with the Secretless Broker project conceptually, I have never touched the codebase or tinkered with the project.
In this blog post, I will write about my experience as an outside contributor to validate their open source contribution experience for the Secretless Broker project and how that gave the Secretless Broker team the confidence in the ease-of-use and quality of their project.
Upon arrival to the team’s office, I sat with a Secretless Broker team member to run through the project at a high level. We tried to keep it at a high level to remain consistent with the community user’s experience when he or she is first introduced to the project by a salesperson or by a developer at a convention. During this knowledge transfer stage, I was acting as a community member and, thus, had to navigate the forward-facing Secretless Broker documentation and codebase to understand the project. As the more technical questions arose, I wrote them down to add them to the docs later.
Once I became familiar with the code and its flow, I was ready to hop in and begin implementing my own Connector Plugin. I looked at other plugins to see how they have been implemented, but quickly became unsure which part of the code was general to all plugins and which was platform-specific. After some digging in the docs and exploring the other plugins, I realized that the instructions for adding a new plugin weren’t as clear as the Secretless Broker team intended. To ease the process, I wrote a blueprint with the required structs and functions the plugin needed to work with the Secretless Broker and some “TODO” comment for myself, describing what needed to be done in each function. Once I had this blueprint, it was much easier to fill in the logic of my Connector Plugin. A short while later, I finished implementing the Connector Plugin and provided end-to-end tests for my addition.
As part of my effort to improve the contribution process, I tried to think how I could make the experience I just had easier for future contributors. I noticed that it was much easier for me to add the actual logic of the Connector Plugin once I had a blueprint written. Consequently, I added a template Connector that spoon-feeds how to implement Secretless Broker Connector Plugins. With the Connector template, Secretless Broker Connector Plugin can be implemented by following the steps detailed below:
- Copy the contents of the template directory into a new folder under the “connectors” directory.
- Fill in the logic and configurations according to the “TODO” comments.
- Copy the contents of the “template_test” directory into a new folder: “test/my_connector.”
- Fill in the test scripts and configurations according to the “TODO” comments.
And voilà – you have a new Secretless Broker Connector Plugin!
After I opened a new PR for the dev team to review, we went on to improve the documentation based on the notes we wrote down earlier. Documentation validation should be part of a DOD for any product or feature. Feedback on documentation is crucial, because there is often a misalignment between what the product developer believes to be trivial and what a contributor, or a user, believes to be complex.
Taking on the contributor persona proved to be successful! The challenges I faced, and that future contributors would have faced, were not visible to members of the Secretless Broker team as they were too familiar with the code. The Secretless Broker team was able to get immediate feedback on their contributing process and tailor it accordingly. I will be sure to adopt this process with my own team and I strongly encourage you to try it in yours too.
Secretless Broker is an open source project from CyberArk. This project and other open source projects are a part of the CyberArk Commons community, a completely open community dedicated to developers, engineers, cybersecurity researchers and other technically minded people. To talk more about my experience or other exciting open initiatives from CyberArk, join me on Discuss.CyberArkCommons.org.
Interested in learning more about contributing to the Secretless Broker project? Head over here!
Oren Ben-Meir is a Software Engineer at CyberArk. He is passionate about exploring new areas, both in code bases and around the world. Oren loves to pass on the knowledge and experience he acquired along the way and guide others in their own personal journey.