Forem: OpenSauced

OpenSauced on Azure: Lessons learned from a near-zero downtime migration

John McBride — Tue, 15 Oct 2024 16:50:08 +0000

At the beginning of October, the OpenSauced engineering team completed a weeks-long
migration of our infrastructure, data, and pipelines to Microsoft Azure. Before this move, we had several bespoke container Apps on Digital Ocean alongside managed PostgreSQL databases.

This setup worked well for a while and was a great way to bootstrap. But, because we lacked GitOps, infrastructure-as-code (IaC) tooling, and a structured method for storing secrets in those early days, our app configurations could be brittle, prone to breaking during upgrades or releases, and difficult to scale in a streamlined manner.

We ultimately decided to migrate our core backend infrastructure from DigitalOcean to Azure, consolidating everything into a unified environment. This move allowed us to capitalize on our existing Azure Kubernetes Service (AKS) infrastructure and fully commit to Kubernetes as our primary service and container orchestration platform.

Azure Kubernetes Service for container runtimes

If you've read any of my previous engineering deep dives (including Technical Deep Dive: How We Built the Pizza CLI Using Go and Cobra, How we use Kubernetes jobs to scale OpenSSF Scorecard, and How We Saved 10s of Thousands of Dollars Deploying Low Cost Open Source AI Technologies At Scale with Kubernetes), you know that we already deploy several AI services and core data pipelines on AKS (primarily the services that power StarSearch).

To simplify our infrastructure and make the most of our existing compute resources in our AKS clusters, we adopted a "monolithic cluster" approach. This means we’re deploying all infrastructure, APIs, and services to the same AKS clusters, centralizing control, management, deployment, and scaling.

The benefits are clear: we avoid the complexity of multi-cluster management, consolidate our networking within a single region, and streamline operations for our small, agile engineering team.

However, this approach has trade-offs we may need to tackle in the future. As OpenSauced grows and scales, we’ll need to reassess and likely adopt a multi-region or multi-cluster strategy to support a globally distributed network. This decision was made with a conscious understanding of the scalability challenges we may face in the future, but for now, this approach gives us the flexibility and simplicity we need.

Choosing a Kubernetes Ingress controller

With AKS now handling all our backend infrastructure, including public-facing APIs, we needed an ingress solution for routing external traffic into our clusters. This also required load balancing, firewall management, Let's Encrypt certificates for SSL, and security policies.

We chose Traefik as our Kubernetes ingress controller. Traefik, a popular choice in the Kubernetes community, is an "application proxy" that offers a rich set of features while being easy to set up. With Traefik, what could have been a complex, error-prone task became an intuitive and streamlined integration into our infrastructure.

Using Pulumi for infrastructure as code and deployment

A key part of our migration was adopting Pulumi as our infrastructure-as-code solution. Before this, our infrastructure setup was a bit ad-hoc, with various configurations and third-party services stitched together manually. When we needed a new cloud service or we were ready to deploy some new API service, we'd piece-meal the different bits together in cloud dashboards and build some custom automation in GitHub actions. While this worked in the very early stages of OpenSauced, it quickly became brittle and hard to manage at scale or across an engineering team.

Pulumi offers several benefits that have already had a noticeable impact on our workflows and engineering culture:

Environment Reproducibility: We can easily create and replicate environments, whether spinning up a new Kubernetes cluster or a full staging environment. It’s as simple as creating a new Pulumi stack.
Simple, Consistent Deployments: Deployments are straightforward, repeatable, and integrated into our CI/CD pipelines.
State and Secret Management: Pulumi provides a built-in mechanism for storing state and secrets, which can be securely shared across the entire engineering team.
GitOps Compatibility: By leveraging Pulumi’s tight integration with Git, we can adopt deeper GitOps workflows, bringing more automation and consistency to our infrastructure management.

Overall, Pulumi has significantly reduced the friction around infrastructure management and deploying new services, allowing us to focus on what really matters — building OpenSauced!

Azure Flexible servers for managed Postgres

For the data layer at OpenSauced (including user data, user assets, and GitHub repository metadata), we previously used DigitalOcean’s managed PostgreSQL service. For our migration to Azure, we opted for Azure Database for PostgreSQL with the Flexible Server deployment option.

This service gives us all the benefits of a managed database solution, including automated backups, restoration capabilities, and high availability. The bonus here is that we can co-locate our data with our AKS clusters in the same region, ensuring low-latency networking between our services on-cluster and the database.

Looking ahead, as our user base grows, we’ll need to explore data replication and distribution to additional regions to enhance availability and redundancy. But for now, this managed solution meets our needs and positions us well for future scalability.

Hats off to the Azure Postgres team on enabling a smooth and near zero downtime migration of our data. All in all, using Azure's provided migration tools, moving everything over took less than 5 minutes. We completed the production migration with minimal end user impact. Because we used Pulumi to configure all our containers on-cluster and also deploy the Postgres flexible servers, we could quickly and easily re-deploy our containers with different configurations to be ready to use the new databases.

Between our Kubernetes environment, Pulumi IaC tooling, and Azure's sublime migration tools, we were able to complete a full production migration seamlessly.

Grafana Observability

As part of this migration, we also made some enhancements to our observability stack to ensure that our backend infrastructure is properly monitored. We use Grafana for observability, and during the migration, we deployed Grafana Alloy on our clusters. Alloy integrates seamlessly with Prometheus for metrics and Loki for log aggregation, giving us a powerful observability framework.

With these tools in place, we have a comprehensive view of our system’s health, allowing us to monitor performance, detect anomalies, and respond to issues before they impact our users. Additionally, our integration with Grafana’s on-call and alerting features enable our engineering team to respond to incidents and ensure OpenSauced stays healthy.

A huge thank you to our Microsoft Azure partners in enabling us to make this transition, providing their expertise, and supporting us along the way!!

As always, stay saucy friends!!

The Hidden Cost of Free: Why Open Source Sustainability Matters

BekahHW — Thu, 10 Oct 2024 15:14:40 +0000

According to Manuel Hoffmann, Frank Nagle and Yanuo Zhou, in The Value of Open Source Software for the HBS Working Paper Series:

We estimate the supply-side value of widely-used OSS is $4.15 billion, but that the demand-side value is much larger at $8.8 trillion. We find that firms would need to spend 3.5 times more on software than they currently do if OSS did not exist. The top six programming languages in our sample comprise 84% of the demand-side value of OSS. Further, 96% of the demand-side value is created by only 5% of OSS developers.

This figures alone should alert us to the critical importance of open source software. But somehow, despite this incredible value, the open source ecosystem still faces major sustainability challenges that will impact its future, and us all.

Beyond the numbers, open source enables innovation, creates opportunities for global collaboration, and provides critical digital infrastructure relied upon by businesses, governments, and people around the world. Projects like the Linux kernel, Python, Kubernetes, Node.js, and countless others create the foundation for everything from cloud computing and AI to mobile apps and IoT devices.

Despite the advancements we've made via open source, we're still facing a crisis of sustainability. As Nadia Eghbal outlined in “Working in Public,” open source often suffers from a tragedy of the commons: while everyone benefits from open source software, the burden of maintaining it falls on a small group of often unpaid or underpaid individuals.

Understanding the Tragedy of the Commons

The tragedy of the commons originates from economics and ecology. It describes a situation where individual users, acting independently according to their own self-interest, deplete or use up a shared resource, even though it's not in anyone’s long-term interest for this to happen. The “commons” refers to resources available to all members of a society, like air, water, or, in this context, open source software.

Application to Open Source Software

In open source, the “commons” is the collective body of software that is freely available for anyone to use, modify, and distribute. While this model encourages innovation and reduces barriers to entry, it also presents challenges:

Unequal Contribution to Benefit Ratio: Many organizations and individuals use open source software in their products and services, gaining significant benefits in terms of cost savings and faster development. However, the responsibility of maintaining and updating these projects often falls on a small group of maintainers who may not receive adequate compensation or recognition for their work.
Maintenance Burden: As software projects grow in popularity, the demands on maintainers increase. They have to address bug reports, security vulnerabilities, feature requests, and support inquiries, which can become overwhelming without sufficient resources.
Sustainability Challenges: Without proper funding or support, maintainers may experience burnout, leading to neglected projects. This can result in security risks, decreased software quality, and ultimately, a decline in the utility of the software for all users.

To learn more about what happens when maintainers leave a project, check out The Silent Crisis in Open Source: When Maintainers Walk Away.

Economic Implications

The difference between those who benefit from open source software and those who maintain it raises economic concerns as well:

Free Riders: Companies often use open source software extensively without contributing back, either through code contributions, funding, or other support.
Lack of Incentives: The traditional market mechanisms that incentivize product improvement and maintenance are weaker in open source projects, because the software is freely available.

The tragedy of the commons in open source software reflects an imbalance between widespread usage and concentrated maintenance responsibilities. While everyone benefits from the collaborative and open nature of these projects, without proactive measures to support maintainers, the sustainability of open source is at risk.

Let's think about this from another perspective. What if our fire departments were all volunteers. They spend the countelss hours training, they're often on call 24/7 to protect our communities from fires and other emergencies, and they aren't paid.

But we also need to recognize that companies build skyscrakers, factories, and complexes that are also protected by these unpaid firefighters. In this scenario, these companies also might be able to forego fire safety systems and insurance, while they still get the benefits of the volunteer labor of the firefighters.

The firefighters would probably have to find a way to bring in income to pay their own bills, so they may end up being exhausted from essentially working two jobs - including one that's incredibly physically demanding. So now, we're left with exhausted fire fighters who might end up making mistakes, having a slow response time, or may be burnt out and quit.

It's pretty clear that this is not a safe situation. And yet, this is what we're accepting in open source. We're creating an environment that's setting us all up for failure.

The Challenge of Funding and Recognition

Part of the sustainability problem is the funding crisis. The 2024 Tidelift State of the Open Source Maintainer Report reveals that 60% of maintainers remain unpaid for their work. Considering the importance maintainers play in maintaining the digital infrastructure that powers our world, this lack of financial support is problemmatic at best.

The Tidelift report also showed that maintainers overwhelmingly prefer predictable, recurring income over one-time payments to better manage their ongoing work. So even when funding is available, it may not be given in a way that best supports the maintainers who need it most.

In “Working in Public: The Making and Maintenance of Open Source Software,” Eghbal emphasizes how open source maintainers are often underappreciated and face burnout. She argues that maintaining a healthy ecosystem requires both financial support and community appreciation for those who contribute regularly. The invisible labor behind these projects keeps them operational and secure, but it often goes unrecognized.

The OSS Pledge: Sentry’s Model for Direct Impact

Sentry’s OSS Pledge serves as a model for how companies can take concrete steps to support open source sustainability. The Pledge calls for companies to pay a minimum of $2000 per year per full-time equivalent developer on their staff to open source maintainers of their choosing. This approach aims to create a new social norm in the tech industry of companies paying open source maintainers directly, addressing the one of the root causes of maintainer burnout and related security issues.

While other forms of support like hiring developers to work on open source or providing in-kind gifts are valuable, the Pledge emphasizes the importance of direct cash payments. This focus ensures that underpaid and overworked maintainers of critical open source projects can pay their bills, leading to a healthier, fairer, more stable, and more secure open source ecosystem.

Open Source and Sustainable Development

It's not just economic and technological impacts that make open source important; open source has the potential to play a major role in addressing global challenges. The Linux Foundation’s Open Source for Sustainability report examines how open source projects can significantly advance the United Nations Sustainable Development Goals (SDGs).

For instance, projects like AgStack help farmers make data-driven decisions to increase yields, contributing to goals like Zero Hunger and Responsible Consumption. Open standards, open AI models, and open data allow for more collaboration, reduce waste, and improve transparency across various sectors.

However, to be able to actualize this potential, we have to prioritize the sustainability of both the projects and their maintainers. According to Eghbal, the perpetual nature of open source development needs continuous support, because without it, these projects are at risk of stagnation or worse, abandonment.

The Security Imperative

The sustainability crisis in open source isn’t just about funding—it’s also a matter of security. The Tidelift report reveals that paid maintainers are significantly more likely to implement critical security practices. This is becoming more and more important as security threats continue to grow in sophistication. (Read more about new legislation to improve cybersecurity for NASA.)

The Log4j vulnerability heightened concerns, with many maintainers feeling less trustful of contributors. We need secure, well-maintained projects. Paid maintainers can generally spend more time on security improvements and maintenance.

Eghbal points out that many essential open source projects are maintained by individuals or small teams with limited resources. This fragile support system can make widely-used software vulnerable to security breaches, as maintainers may not have the bandwidth to address every vulnerability or request. Prioritizing financial and structural support is necessary to decrease these risks.

Solutions

So, what can be done? First, we need a paradigm shift in how we think about and support open source work. Companies that benefit from open source need to step up their financial support. The Linux Foundation’s work in creating funding models and governance structures for open source projects is a step in the right direction, but we need more widespread adoption is needed.

Governments also have a responsibility to consider the long-term impact of their dependence on open source. Recognizing open source as critical national infrastructure and providing funding and support could help ensure its long-term viability.

For individual developers and users of open source, consider contributing back—whether through code, documentation, or financial support. If you're in a position to influence your company's policies, advocate for supporting open source projects through consistent sponsorships or by creating employee time for contributions to the projects they use.

Take time to look at and understand your dependencies. Create an SBOM Workspace and look at the security ratings of your dependencies. Identify the lottery factor of the projects. If you see there's a high lottery factor, then those projects might need to be the priority for your support.

Takeaways

The open source model has created an amazing history of technological innovation and collaboration. But like any commons, it requires stewardship and support to thrive. The sustainability of open source is not just a technical issue — it’s a societal imperative. Working together — companies, governments, developers, and users — we need to make sure that the open source ecosystem continues to make progress.

Recognizing the “invisible labor” involved in open source is a first step toward making sure that the individuals behind these projects can continue their work without facing burnout. Let's elevate the status of maintainers and give them the recognition and support they deserve.

Transparency is Open Source Currency: Lessons from PearAI

BekahHW — Thu, 03 Oct 2024 11:40:01 +0000

On September 28, PearAI’s founder, Duke Pan (also known as “FryingPan” online), shared a tweet announcing the launch of PearAI, an AI-powered code editor which they described as a "fork of VSCode." This wasn't false, but it wasn't the full truth either, and people were quick to point this out.

It turns out that PearAI was not just a fork of VSCode; it was also a fork of Continue.dev, an AI-powered extension of VSCode. The problem? Continue.dev was licensed under the Apache 2.0 License, while PearAI was initially launched with a proprietary license called the "Pear Enterprise License."

When the community discovered that PearAI had essentially cloned Continue.dev without adding significant new features or providing proper attribution, accusations of plagiarism and license violations arose.

But did PearAI really do anything wrong? The answer is a bit more nuanced than a simple yes or no. PearAI did eventually switch back to the Apache 2.0 License and issue a public apology, but the public felt that PairAI had violated the trust and expectations of the open source community - which can have far-reaching consequences.

In open source, transparency isn’t just a virtue — it’s a requirement.

The Importance of Transparency in Open Source

Transparency is a foundational principal of open source development. It goes beyond making code publicly available; it means clear communication about a project's origins, development processes, and in interactions with contributors.

For example, jsx-email is a fork of react-email that was created to address some of the limitations of the original project. However, the maintainers of jsx-email continue to be transparent about the project's origins in their README.

The level of transparency can significantly impact the project's success and community engagement. It also mitigates the risk of misunderstandings and accusations of impropriety. Projects that lack transparency can alienate contributors and users.

Case Study: PearAI vs. Continue.dev

The PearAI and Continue.dev story shows how a lack of transparency can lead to community distrust and community backlash. PearAI’s founder, Duke Pan, admitted that PearAI was built on Continue’s code but that information wasn't easily accessible in its public-facing materials. The situation was worsened when the company introduced a proprietary license, creating the impression that PearAI was not just a fork, but an entirely new product.

After a social media storm, calling out the misleading nature of the project, Pan issued a public apology and switched back to the Apache 2.0 license.

In the long term, we'll see if PearAI can recover from this incident and rebuild trust with the open source community. At the very least, we should take this as a cautionary tale for other projects about the importance of transparency and proper attribution.

Data-Driven Insights: The Impact of Transparency on Community Engagement

The transparency issues between PearAI and Continue.dev didn’t just affect the trust within the open source community — they also increased the visibility and engagement for both projects. Looking at the data shows that the controversy caused notable spikes in stars and forks for both repositories, though the dynamics behind each project’s growth tell different stories.

Continue.dev has demonstrated strong community engagement over the past 90 days. The project has amassed a total of 17.1k stars, with over 900 stars being added in the last seven days at an average of 46 per day. The number of forks, at 1.3k total, with 490 in the last 90 days, shows a healthy growth rate of 5 forks per day. Interestingly, these numbers reflect a surge of interest likely driven by the controversy, as people went to Continue.dev either in support or to compare it with PearAI.

If you want to see a comparison, check out our Continue v. Pear Workspace

PearAI, despite the initial backlash, has also seen notable engagement, though at a much smaller scale - which is to be expected of a new project. PearAI recorded 524 stars during this period, with 1,735 stars gained in the last 90 days and an average of 19 stars per day. It also experienced an increase in forks at 79 over this time period, with 290 total forks over 90 days and 3 forks per day on average. While its numbers are smaller than Continue.dev’s, this sudden increase indicates that the announcement of the project and controversy has lead to heightened activity.

The old adage that “there’s no such thing as bad publicity” seems to hold true in this case. The controversy surrounding PearAI has inadvertently boosted its visibility and engagement, even if the attention was negative.

However, a deeper dive into the numbers reveals a more nuanced picture of community engagement. Over the last seven days:

Continue.dev has seen ten outside contributors, with 4 recurring.
Continue.dev has had 25 opened pull requests with six merged.
PearAI has seen no outside contributors and only seven opened pull requests.

These metrics highlight a significant disparity in active community participation between the two projects.

Continue.dev's ability to get and retain outside contributors suggests an engaged community. PearAI's lack of outside contributors and fewer pull requests might mean challenges in converting initial interest into sustained community engagement.

While controversy can drive short-term attention, it's the foundation of trust, transparency, and community goodwill that is more likely to lead to long-term engagement and project health.

For the broader open source community, this case study serves as a reminder of the importance of:

Maintaining transparency from the outset of a project
Quickly addressing and rectifying any missteps in community relations
Focusing on building a welcoming environment for contributors beyond initial marketing metrics

As we continue to watch how these projects progress, it will be interesting to see how these engagement metrics evolve and whether PearAI can bridge the gap in community participation.

The Consequences of Failing Transparency

When open source projects fail to be transparent, they risk losing the community’s trust. PearAI’s case illustrates this well. Its initial missteps led to a loss of credibility, with many contributors questioning the project’s legitimacy. The community backlash was swift, and PearAI’s subsequent efforts to rectify the situation were seen as too little, too late by some.

In open source, reputation can be everything. Projects that don’t respect the principles of open source development—particularly transparency and proper licensing—face long-term damage. Even after reverting to an open source license and offering a public apology, PearAI will likely have to work hard to regain the trust of developers and contributors.

Lessons Learned for Open Source Projects

The PearAI-Continue.dev situation offers several valuable lessons for open source projects:

Clear communication: From the start, open source projects need to be clear about their origins, whether they are forks, original creations, or collaborative efforts. PearAI could have avoided much of its backlash by being upfront about its relationship with Continue.dev.
Respect for licenses: Proper attribution isn't just a courtesy; it’s a legal and ethical requirement. By applying a proprietary license to a forked project, PearAI violated one of the key principles of open source, which contributed to the backlash.
Community Trust as a Competitive Advantage: Beyond just attracting contributors, transparent projects create deeper community trust, which is a long-term competitive advantage.
Long-term Vision: Projects should consider how their actions align with the long-term goals of building a thriving, collaborative community. Short-term gains in visibility or proprietary advantages may come at the cost of sustainable growth and community support.

Last Thoughts

Transparency isn’t just a best practice in open source — it’s the currency that keeps communities thriving. The PearAI-Continue.dev situation illustrates how quickly things can go wrong when transparency is lacking. While PearAI eventually corrected its mistakes, the damage to its reputation and community trust will take time to heal. This case serves as a reminder to all open source projects: be transparent, respect your contributors, and uphold the principles that make open source a powerful movement.

Building a culture of shared ownership

BekahHW — Tue, 24 Sep 2024 16:36:48 +0000

Back in 2020, when the pandemic hit, I lost my first tech job. It was the same day I picked up my kids’ books from school, expecting a three-week break. They never returned that year. Somehow, I found myself interviewing for a DevOps position - at the time I didn’t even know what DevOps was. After the first interview, the interviewer told me to read The Phoenix Project and then she’d give me a second interview.

In the book, Brent is the go-to Ops Engineer, the one with all the answers, putting out fires, and saving the day. The problem? Brent is a bottleneck, not a multiplier.

The Hidden Cost of Siloed Knowledge

When knowledge is siloed, we put our teams at risk. What happens to your team when someone goes on vacation? Needs to take some time off? Or even worse, leaves the company? The impact can be stifling and even paralyzing. The hidden cost of siloed knowledge can lead to a phenomenon known as "knowledge hoarding," where team members, whether intentionally or not, become protective of their expertise and don’t share it with others. More costs of siloed knowledge include:

Single Points of Failure: Key expertise is held by a few, creating dependency.
Redundant Efforts: Without shared knowledge, teams may unknowingly duplicate work.
Slow Onboarding: New team members struggle to piece together fragmented information.

If expertise is spread throughout your team and you don’t rely on any single person, you improve your team’s stability and to achieve success. The cost of siloed knowledge is a lot steeper than we realize.

Siloed knowledge leads to optimizing locally, but sub-optimizing globally. What does that mean? It means that teams start to become hyper-efficient in their own bubbles, but the organization as a whole starts to suffer. You’ll see your top engineers reinventing the wheel in different corners of the company, doing redundant work in isolation. And when you bring new people onto the team, there’s no clear path for knowledge sharing with slow onboarding as they try to put together fragmented knowledge. This isn’t a minor inconvenience - you pay for this in time, morale, and missed opportunities.

In the context of developer culture, this problem can be particularly damaging, leading to inconsistent practices across teams and impeding the development of a cohesive engineering culture. Developers thrive when information flows freely, collaboration is valued, and when everyone has access to the knowledge they need to exceed. Even within small, agile teams like the ‘two-pizza teams’ popularized by Amazon (teams small enough to be fed by two pizzas), knowledge silos can form if deliberate steps aren’t taken to encourage sharing.

Shared Ownership: not about blame, about empowerment

I know some people start to get nervous when we talk about shared ownership. You might think this means shifting blame around when things go wrong. But that’s missing the point. It’s not about pointing fingers. It’s about embracing a team responsibility to contribute, learn, and grow. It’s about creating an environment where everyone feels responsible for the success of the project, not just their own tasks.

When we embrace shared ownership, we’re acknowledging that everyone’s insights and ideas matter and that they have the power to make an impact on the project.

In a two-pizza team structure, shared ownership isn't just beneficial—it’s necessary. Small teams are designed to be autonomous, fast-moving, and highly collaborative. When everyone on the team has a comprehensive understanding of the project, everyone can make better decisions, avoid duplicating efforts, and maintain high standards across all parts of development. This type of collaboration requires a culture where expertise is shared openly and where the success of the team is prioritized over the individual.

The CODEOWNERS File: A Tool for Knowledge Sharing

This is where a CODEOWNERS file can help teams get started. If you know what a CODEOWNERS file is, you might think of it as a way to assign responsibility for review of a particular codebase on GitHub. But I think a better way to think about it is as a map of expertise - a file that outlines the go-to people for different parts of the codebase.

I want to take a minute to flip the idea that it’s restricting access or creating gatekeepers, and ask you to think of it as a way to highlight expertise and encourage collaboration. When the pull request comes in, the right people get notified automatically. This also means that when someone has a question, they know exactly who to reach out to.

As part of this, it’s important to remember that a CODEOWNERS file isn’t meant to be a static document. It should change as your team grows and as people develop new areas of expertise. Think of it as a living document representing your team’s collective knowledge.

Building a Culture of Shared Knowledge and Learning

Don’t get me wrong: a codeowners file won’t solve all your problems. It’s a tool, and like any tool, its effectiveness depends on how you use it. The real goal should be to build a culture of shared knowledge and continuous learning.

Let’s shift our mindset from a culture of ownership to a culture of expertise.

Ownership implies exclusivity. “This is my code, my project, my responsibility.” This mentality can create barriers and discourage collaboration.

Expertise, on the other hand, is something to be shared and celebrated. Focusing on expertise encourages the mindset of having a deep knowledge and a willingness to help others understand it as well.

When we build a culture of expertise, we also shift the value, not from how indispensable you are, but how much you elevate the whole team. You’re not a code “guardian.” You’re a multiplier. And we all want multipliers on our teams and in our organizations.

The OpenSauced Solution: pizza-cli codeowners

So what can you do today? At OpenSauced, we’ve developed a codeowners command for our pizza-cli to do the heavy lifting of analyzing your git history, generating a CODEOWNERS file, and keeping it up to date automatically. This means you don’t have to guess who to contact if you have a question about a particular file. (I talk more about this in The Problem of Knowledge Debt in Tech.)

For each file in your codebase, the pizza-cli + GitHub Action assigns up to three “owners.” Why three? Three creates a balance between clear accountability and shared knowledge by not limiting to a single owner. At the same time, you're also not diluting responsibility across too many people.

Remember, this isn’t about creating boundaries or “exclusive” territories. It’s about surfacing expertise within your team, starting conversations, and learning from each other.

Start Small, Think Big

Head over to the pizza-cli and give it a try. You can start small-test it with a single project or team and start the conversation about code ownership and expertise.

Tools like the pizza-cli are just the beginning. The goal is a knowledge-rich developer culture where everyone thrives.

Tools like the pizza-cli can be helping in making sure that no one person becomes a bottleneck.

Creating a developer culture of shared knowledge and continuous learning is an ongoing process, but it’s worth the investment. Let’s build teams that elevate each other, embrace expertise, and grow together.

Technical Deep Dive: How We Built the Pizza CLI Using Go and Cobra

John McBride — Mon, 23 Sep 2024 16:07:21 +0000

Last week, the OpenSauced engineering team released the Pizza CLI, a powerful and composable command-line tool for generating CODEOWNER files and integrating with the OpenSauced platform. Building robust command-line tools may seem straightforward, but without careful planning and thoughtful paradigms, CLIs can quickly become tangled messes of code that are difficult to maintain and riddled with bugs. In this blog post, we'll take a deep dive into how we built this CLI using Go, how we organize our commands using Cobra, and how our lean engineering team iterates quickly to build powerful functionality.

Using Go and Cobra

The Pizza CLI is a Go command-line tool that leverages several standard libraries. Go’s simplicity, speed, and systems programming focus make it an ideal choice for building CLIs. At its core, the Pizza-CLI uses spf13/cobra, a CLI bootstrapping library in Go, to organize and manage the entire tree of commands.

You can think of Cobra as the scaffolding that makes a command-line interface itself work, enables all the flags to function consistently, and handles communicating to users via help messages and automated documentation.

Structuring the Codebase

One of the first (and biggest) challenges when building a Cobra-based Go CLI is how to structure all your code and files. Contrary to popular belief, there is no prescribed way to do this in Go. Neither the go build command nor the gofmt utility will complain about how you name your packages or organize your directories. This is one of the best parts of Go: its simplicity and power make it easy to define structures that work for you and your engineering team!

Ultimately, in my opinion, it's best to think of and structure a Cobra-based Go codebase as a tree of commands:

├── Root command
│   ├── Child command
│   ├── Child command
│   │   └── Grandchild command

At the base of the tree is the root command: this is the anchor for your entire CLI application and will get the name of your CLI. Attached as child commands, you’ll have a tree of branching logic that informs the structure of how your entire CLI flow works.

One of the things that’s incredibly easy to miss when building CLIs is the user experience. I typically recommend people follow a “root verb noun” paradigm when building commands and child-command structures since it flows logically and leads to excellent user experiences.

For example, in Kubectl, you’ll see this paradigm everywhere: “kubectl get pods”, “kubectl apply …“, or “kubectl label pods …” This ensures a sensical flow to how users will interact with your command line application and helps a lot when talking about commands with other people.

In the end, this structure and suggestion can inform how you organize your files and directories, but again, ultimately it’s up to you to determine how you structure your CLI and present the flow to end-users.

In the Pizza CLI, we have a well defined structure where child commands (and subsequent grandchildren of those child commands) live. Under the cmd directory in their own packages, each command gets its own implementation. The root command scaffolding exists in a pkg/utils directory since it's useful to think of the root command as a top level utility used by main.go, rather than a command that might need a lot of maintenance. Typically, in your root command Go implementation, you’ll have a lot of boilerplate setting things up that you won’t touch much so it’s nice to get that stuff out of the way.

Here's a simplified view of our directory structure:

├── main.go
├── pkg/
│   ├── utils/
│   │   └── root.go
├── cmd/
│   ├── Child command dir
│   ├── Child command dir
│   │   └── Grandchild command dir

This structure allows for clear separation of concerns and makes it easier to maintain and extend the CLI as it grows and as we add more commands.

Using go-git

One of the main libraries we use in the Pizza-CLI is the go-git library, a pure git implementation in Go that is highly extensible. During CODEOWNERS generation, this library enables us to iterate the git ref log, look at code diffs, and determine which git authors are associated with the configured attributions defined by a user.

Iterating the git ref log of a local git repo is actually pretty simple:

// 1. Open the local git repository
repo, err := git.PlainOpen("/path/to/your/repo")
if err != nil {
        panic("could not open git repository")
}

// 2. Get the HEAD reference for the local git repo
head, err := repo.Head()
if err != nil {
        panic("could not get repo head")
}

// 3. Create a git ref log iterator based on some options
commitIter, err := repo.Log(&git.LogOptions{
        From:  head.Hash(),
})
if err != nil {
        panic("could not get repo log iterator")
}

defer commitIter.Close()

// 4. Iterate through the commit history
err = commitIter.ForEach(func(commit *object.Commit) error {
        // process each commit as the iterator iterates them
        return nil
})
if err != nil {
        panic("could not process commit iterator")
}

If you’re building a Git based application, I definitely recommend using go-git: it’s fast, integrates well within the Go ecosystem, and can be used to do all sorts of things!

Integrating Posthog telemetry

Our engineering and product team is deeply invested in bringing the best possible command line experience to our end users: this means we’ve taken steps to integrate anonymized telemetry that can report to Posthog on usage and errors out in the wild. This has allowed us to fix the most important bugs first, iterate quickly on popular feature requests, and understand how our users are using the CLI.

Posthog has a first party library in Go that supports this exact functionality. First, we define a Posthog client:

import "github.com/posthog/posthog-go"

// PosthogCliClient is a wrapper around the posthog-go client and is used as a
// API entrypoint for sending OpenSauced telemetry data for CLI commands
type PosthogCliClient struct {
    // client is the Posthog Go client
    client posthog.Client

    // activated denotes if the user has enabled or disabled telemetry
    activated bool

    // uniqueID is the user's unique, anonymous identifier
    uniqueID string
}

Then, after initializing a new client, we can use it through the various struct methods we’ve defined. For example, when logging into the OpenSauced platform, we capture specific information on a successful login:

// CaptureLogin gathers telemetry on users who log into OpenSauced via the CLI
func (p *PosthogCliClient) CaptureLogin(username string) error {
    if p.activated {
        return p.client.Enqueue(posthog.Capture{
            DistinctId: username,
            Event:      "pizza_cli_user_logged_in",
        })
    }

    return nil
}

During command execution, the various “capture” functions get called to capture error paths, happy paths, etc.

For the anonymized IDs, we use Google’s excellent UUID Go library:

newUUID := uuid.New().String()

These UUIDs get stored locally on end users machines as JSON under their home directory: ~/.pizza-cli/telemtry.json. This gives the end user complete authority and autonomy to delete this telemetry data if they want (or disable telemetry altogether through configuration options!) to ensure they’re staying anonymous when using the CLI.

Iterative Development and Testing

Our lean engineering team follows an iterative development process, focusing on delivering small, testable features rapidly. Typically, we do this through GitHub issues, pull requests, milestones, and projects. We use Go's built-in testing framework extensively, writing unit tests for individual functions and integration tests for entire commands.

Unfortunately, Go’s standard testing library doesn’t have great assertion functionality out of the box. It’s easy enough to use “==” or other operands, but most of the time, when going back and reading through tests, it’s nice to be able to eyeball what’s going on with assertions like “assert.Equal” or “assert.Nil”.

We’ve integrated the excellent testify library with its “assert” functionality to allow for smoother test implementation:

config, _, err := LoadConfig(nonExistentPath)
require.Error(t, err)
assert.Nil(t, config)

Using Just

We heavily use Just at OpenSauced, a command runner utility, much like GNU’s “make”, for easily executing small scripts. This has enabled us to quickly onramp new team members or community members to our Go ecosystem since building and testing is as simple as “just build” or “just test”!

For example, to create a simple build utility in Just, within a justfile, we can have:

build:
  go build main.go -o build/pizza

Which will build a Go binary into the build/ directory. Now, building locally is as simple as executing a “just” command.

But we’ve been able to integrate more functionality into using Just and have made it a cornerstone of how our entire build, test, and development framework is executed. For example, to build a binary for the local architecture with injected build time variables (like the sha the binary was built against, the version, the date time, etc.), we can use the local environment and run extra steps in the script before executing the “go build”:

build:
    #!/usr/bin/env sh
  echo "Building for local arch"

  export VERSION="${RELEASE_TAG_VERSION:-dev}"
  export DATETIME=$(date -u +"%Y-%m-%d-%H:%M:%S")
  export SHA=$(git rev-parse HEAD)

  go build \
    -ldflags="-s -w \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Version=${VERSION}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Sha=${SHA}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Datetime=${DATETIME}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.writeOnlyPublicPosthogKey=${POSTHOG_PUBLIC_API_KEY}'" \
    -o build/pizza

We’ve even extended this to enable cross architecture and OS build: Go uses the GOARCH and GOOS env vars to know which CPU architecture and operating system to build against. To build other variants, we can create specific Just commands for that:

# Builds for Darwin linux (i.e., MacOS) on arm64 architecture (i.e. Apple silicon)
build-darwin-arm64:
  #!/usr/bin/env sh

  echo "Building darwin arm64"

  export VERSION="${RELEASE_TAG_VERSION:-dev}"
  export DATETIME=$(date -u +"%Y-%m-%d-%H:%M:%S")
  export SHA=$(git rev-parse HEAD)
  export CGO_ENABLED=0
  export GOOS="darwin"
  export GOARCH="arm64"

  go build \
    -ldflags="-s -w \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Version=${VERSION}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Sha=${SHA}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Datetime=${DATETIME}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.writeOnlyPublicPosthogKey=${POSTHOG_PUBLIC_API_KEY}'" \
    -o build/pizza-${GOOS}-${GOARCH}

Conclusion

Building the Pizza CLI using Go and Cobra has been an exciting journey and we’re thrilled to share it with you. The combination of Go's performance and simplicity with Cobra's powerful command structuring has allowed us to create a tool that's not only robust and powerful, but also user-friendly and maintainable.

We invite you to explore the Pizza CLI GitHub repository, try out the tool, and let us know your thoughts. Your feedback and contributions are invaluable as we work to make code ownership management easier for development teams everywhere!

Introducing the OpenSauced Pizza GitHub Action: Automate Your Repository Management

Nick Taylor — Fri, 20 Sep 2024 14:53:00 +0000

Are you looking for an easy way to streamline your repository management tasks? Look no further! We're excited to introduce the OpenSauced Pizza GitHub Action, a powerful tool that brings the functionality of the OpenSauced Pizza CLI directly into your GitHub workflows.

Curious what the Pizza CLI is? 👇

Introducing the Pizza CLI

John McBride for OpenSauced ・ Sep 16 '24

#opensource #codeowners #cli

What is the OpenSauced Pizza GitHub Action?

The OpenSauced Pizza GitHub Action is a custom GitHub Action that allows you to run various commands from the OpenSauced Pizza CLI as part of your automated workflows.

open-sauced / pizza-action

This action runs the OpenSauced pizza CLI in a GitHub Action workflow.

OpenSauced Pizza GitHub Action

This action runs the OpenSauced pizza CLI in a GitHub Action workflow.

About the Pizza CLI

For more information about the pizza-cli. check out the OpenSauced pizza-cli repository.

Usage

To use this action, you need to add the following to a GitHub Actions workflow file. The YAML snippet below uses the command to update your CODEOWNERS file in your repository, but replace it with whatever pizza-cli command you want to run.

name: OpenSauced Pizza Action
on:
  schedule:
    # Run once a week on Sunday at 00:00 UTC
    - cron: "0 0 * * 0"
  workflow_dispatch: # Allow manual triggering

jobs:
  pizza-action:
    runs-on: ubuntu-latest
    steps:
      - name: Pizza Action
        uses: open-sauced/pizza-action@latest
        with:
          # optional and default is "latest". Add this parameter if you want to use a specific version, e.g. v2.0.0
          cli-version:

…

View on GitHub

This action makes it simple to integrate repository management tasks into your continuous integration and deployment processes.

Key Features

Easy Integration: Add the action to your workflow with just a few lines of YAML.
Flexible Command Execution: Run any Pizza CLI command within your GitHub Actions workflow.
Automatic Updates: Schedule regular updates to keep your repository management tasks current.
Optional Commit and Pull Request: Automatically commit changes and create a pull request for the updates made by the Pizza CLI.

Getting Started

To use the OpenSauced Pizza GitHub Action, add the following to your GitHub Actions workflow file:

name: OpenSauced Pizza Action

on:
  schedule:
    # Run once a week on Sunday at 00:00 UTC
    - cron: "0 0 * * 0"
  workflow_dispatch: # Allow manual triggering

jobs:
  pizza-action:
    runs-on: ubuntu-latest
    steps:
      - name: Pizza Action
        uses: open-sauced/pizza-action@latest
        with:
          # optional and default is "latest". Add this parameter if you want to use a specific version, e.g. v2.0.0
          cli-version: "v2.2.0"
          # optional and false by default. Set this to true if you want to have a pull request for the changes created automatically.
          commit-and-pr: "true"
          # optional
          pr-title: "chore: update repository codeowners"

We recommend saving this as pizza-action.yml in the .github/workflows directory of your repository.

This example sets up a weekly run of the Pizza CLI's generate codeowners ./ --tty-disable command, which updates your repository's CODEOWNERS file based on contribution history.

Customization Options

The action provides several inputs for customization:

cli-version: The version of the pizza CLI to use. Default is latest. If using a numbered version, make sure to prefix the version number with v. For example, v2.0.0.
pizza-args: Specify the Pizza CLI command to run (default: generate codeowners ./ --tty-disable).
commit-and-pr: Choose whether to automatically commit changes and create a pull request (default: false).
pr-title: Set a custom title for the pull request (default: chore (automated): OpenSauced updates).

Important Note

The pizza CLI's "generate codeowners" command requires a full repository history to accurately determine code ownership over time. The action sets fetch-depth to 0 to ensure all historical commits are available, allowing for a comprehensive analysis of the project timeline.

Troubleshooting

If you encounter the error pull request create failed: GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest), you need to enable the appropriate permissions. Go to your repository settings, navigate to the Actions section, and check the option "Allow GitHub Actions to create and approve pull requests".

Here’s an example of a recent pull request that was generated by the pizza-action:

chore (automated): OpenSauced updates #4103

github-actions[bot] posted on Sep 15, 2024

This is an automated PR generated by the OpenSauced pizza-action.

View on GitHub

See it in action!

Future Enhancements

While the current version of the Pizza CLI focuses on generating CODEOWNERS files, the OpenSauced team is actively working on expanding its capabilities. In the future, you can expect a wider range of commands to be available, further enhancing your repository management toolkit. Stay tuned for updates!

Conclusion

Bottom line: the OpenSauced Pizza GitHub Action is your ticket to bringing Pizza CLI goodness straight into your GitHub workflow. It's dead simple to set up and takes care of the grunt work. Whether you're managing CODEOWNERS files or leveraging future Pizza CLI features, the Pizza GitHub Action has you covered.

Give it a try and let me know what you think!

Stay saucy peeps!

If you would like to know more about my work in open source, follow me on OpenSauced.

The Problem of Knowledge Debt in Tech

BekahHW — Thu, 19 Sep 2024 16:26:32 +0000

A couple of weeks ago, I came across this Reddit post where a developer was trying to navigate a challenge that many of us in the tech community have also faced: managing code ownership in a large, complex codebase.

With over 100 developers and a massive repository, they were looking for a way to automate the creation of a CODEOWNERS file. Their hope? To automatically assign ownership based on who had worked on each file.

Not everyone in the comments was on board with this idea, calling out that this could be a recipe for disaster. You’re not wrong to be cautious, but let’s not dismiss the underlying need. The OP’s question points to a real issue in the tech industry: how do we manage knowledge and responsibility as the codebase and teams grow?

If you want to see a complex codebase, Kubernetes is a great example, with contributions from thousands of developers across hundreds of organizations. How do they manage it? They use an OWNERS file system that’s been tested and refined over the years.

The Kubernetes approach is about creating a map of expertise, facilitating code reviews, and making sure changes are reviewed by the right people. This system recognizes that in a project of that scale, no single person can know everything. The solution is to create a culture of shared responsibility and continuous learning.

Here’s the thing: what works for Kubernetes might not work for every team. And that’s okay. The key is to understand the principles behind the system and adapt them to work for your team.

When you implement solutions like automated CODEOWNERS generation, keep in mind to:

Embrace shared ownership: The goal isn't to create territorial divides in your code. It's to identify who has the deepest knowledge in different areas, so they can guide and support others.
Keep it dynamic: Your CODEOWNERS file should evolve as your team and codebase grow.
Use it as a guide, not a rule: Code ownership shouldn't be a barrier to contribution. It's about facilitating knowledge sharing, not gatekeeping.

Ensuring that each part of the codebase has an expert responsible for its maintenance and review, effectively helps to manage the hidden debt of lost knowledge.

The Real Cost of Lost Knowledge

Let’s take a look at what knowledge debt costs us:

Time: New team members spend weeks trying to understand systems that could be explained in hours by the right person.
Efficiency: When you’re spending time figuring out what existing code does, or you don’t understand why the original developer made certain changes, you don’t have the time to spend on making meaningful progress.
Morale: Nothing kills motivation faster than feeling lost.
Inefficiency and Redundancy: You might spend days solving a problem that someone else on your team has already cracked. It's like reinventing the wheel, but the wheel is buried somewhere in your Git history, and you don't even know it exists. This isn't just a waste of time; it's a missed opportunity for collaboration and knowledge sharing.
Maintenance Challenges and Siloed Knowledge: As knowledge gaps widen, the cost and complexity of maintaining older parts of the system increase. This can lead to knowledge silos, where only a few individuals understand critical systems, creating bottlenecks and reducing overall team capability.

Every time a developer writes a line of code without clear ownership, every time a key team member leaves without transferring their knowledge, the debt grows and the culture weakens. It compounds over time, making each new feature more costly, each bug more time-consuming to fix, each team interaction less effective. The debt of lost knowledge is often invisible, and we often don't realize it until we're in a crisis.

When the Debt Collectors Come Calling

Eventually, every debt comes due. In tech, this often comes during critical moments:

A production outage caused by a change to a poorly understood component
A missed market opportunity because adding a feature took months instead of weeks
The departure of the last team member who understood a core system, leaving the project effectively "underwater"

These are the moments when companies often realize the real cost of their knowledge debt. But by then, it's often too late for an easy fix.

Enter the CODEOWNERS File: Your Knowledge Map

This is where tools like the CODEOWNERS file come into play. Think of it as a map of expertise for your codebase. But not just any map – a living, breathing document that evolves with your team.

At OpenSauced, we’ve taken this concept to the next level with our pizza-cli codeowners command. It's not just about assigning arbitrary owners to directories. This tool identifies who has the most relevant and recent expertise for each part of your codebase.

What sets it apart is its granularity and balance. It assigns up to three "owners" for each file or directory. Pair this with our pizza GitHub Action, and you've got a system that keeps your expertise map up-to-date automatically. You can learn more about how to get started in Introducing the Pizza CLI.
Generating your CODEOWNERS file using the pizza generate codeowners command automatically creates or updates a CODEOWNERS file, mapping files to the appropriate owners.

Beyond just managing debt, the codeowners command helps create a culture of responsibility and expertise. It makes code ownership visible and actionable, encouraging developers to take pride in their areas of responsibility and seek out opportunities to share their knowledge.

Final Thoughts

It's not hard to accumulate knowledge debt in the name of quick wins and feature delivery. But like any form of debt, ignoring it only makes the problem worse-not just for your codebase, but for your entire engineering culture.

By recognizing knowledge debt for the serious threat it is, and utilizing tools like the pizza cli to manage it, teams can ensure they're building on a solid foundation. They're not just writing code—they're cultivating a culture of ownership, expertise, and collaborative learning.

Remember, every line of code you write is a promise to your future self and your team. Make sure it's a promise you can keep by managing your knowledge debt and creating a culture of knowledge sharing today. The codeowners command is more than just a tool—it's a step towards a more sustainable and efficient development process, and a more collaborative engineering culture.

Introducing the Pizza CLI

John McBride — Mon, 16 Sep 2024 15:13:37 +0000

As software engineering teams and projects scale, a common problem larger organizations can find themselves in is deciphering the “who’s who” of a codebase. This problem only compounds itself if large mono-repos are in use or multiple teams interact in the same space. Developers may find themselves asking “Who do I ask for a review on this? What team owns this part of the code base? Who do I ask for help?”

On the receiving end of this, you may find yourself getting asked questions on things you haven’t been involved in for years. Or you may be missing critical notifications on pieces of code you maintain or your team maintains. Or even worse, there may be cross team miscommunications that cause problems for the code you own.

As teams grow and codebases expand, before too long, it can be very easy to lose the thread on who owns what piece of “knowledge” across your engineering org. This lost context can slow down development, hinder open collaboration, and slowly erode the engineering culture of an engineering organization.

But what if there was a way to automate code ownership, streamline collaboration, and reduce this knowledge debt? Today, the OpenSauced team is very excited to introduce the Pizza CLI, a powerful command-line tool designed to help maintainers, teams, and organizations manage their engineering “ownership” culture and derive insights right on the command line.

Introducing the Pizza CLI

The Pizza CLI is our solution to the challenges of lost context and asking “Who’s who?” Born from discussions with industry experts like Bdougie and Kelsey Hightower, inspired by robust tools used by hyperscale tech companies across the industry, the Pizza CLI empowers teams to automate code ownership and enhance cross org collaboration directly from the command line.

CODEOWNERS Generation: Easily generate GitHub-style CODEOWNERS or Google-style OWNERS files, granularly mapping out who owns which parts of your codebase based on git history, number of lines touched, and current activity. These owner files can then be used in GitHub CODEOWNERS automation or as part of more robust CI/CD.

Attribution Configuration: Use a simple YAML configuration to map commit emails to GitHub usernames and teams, ensuring accurate ownership assignments and easy management of entities within your engineering org.

OpenSauced Integration: Seamlessly connect with OpenSauced to create Contributor Insights pages and metrics, helping you visualize and understand your project's contributor and owner landscape.

Enhanced collaboration for large teams

By clearly defining code ownership in a granular manner and integrating seamlessly with GitHub CODEOWNERS functionality, the Pizza CLI helps you:

Improve Efficiency: Developers know exactly who to reach out to for code reviews or questions, reducing delays, miscommunications, and team misalignments.

Enhance Collaboration: Ownership transparency creates a culture of shared responsibility and teamwork, further enhancing open “inner-source” between teams and developers.

Streamline Onboarding: New team members can quickly identify code owners, making it easier for them to ramp up and contribute confidently. Oftentimes, this can be automated through GitHub’s integration with CODEOWNER files through automatic PR review requests and notifications.

Getting Started with Pizza CLI

Installation



brew install open-sauced/tap/pizza

We offer a number of flexible options for installing the Pizza CLI onto your system (including Homebrew, NPM, Docker, and more). Check out the docs in the repository for a full rundown of the ways you can install this tool.

Validate your install

Check to make sure you can run the Pizza CLI:



pizza version

This will print out the version you have installed. Successfully running this in your terminal means you have successfully installed the CLI!

Generate a config

Before you can start generating codeowner files, you’ll need a YAML configuration that attributes git commit emails with GitHub user logins. You can generate a config through the ”pizza generate config” command:



pizza generate config /path/to/your/git/repo -i

The “-i” flag tells the Pizza CLI to use “interactive” mode. This iterates through the git ref-log and looks at commits and who authored them. It will then ask you to attribute those commit emails to individuals on your team:

Once you’ve finished generating your config, you’ll see that a .sauced.yaml file is now in your git repo where you originally pointed the pizza command to. It’s been populated with the associated logins and emails that can be used to attribute changes in the repository to individual owners.

We encourage you to commit this file to your repository as a core piece of configuration “infrastructure” denoting what individuals have what attributions associated with them. Alternatively, if exposing commit emails in the config is not acceptable, you may choose to add it to a private secret store and pull it down manually to make code attributions for individuals on your teams.

You can also attribute GitHub teams to long lists of emails in your YAML configuration:



attribution:
  # Keys may also be GitHub team names.
  open-sauced/engineering:
    - john@opensauced.pizza
    - other-user@email.com
    - other-user@no-reply.github.com

This way, multiple people can be associated to a single team within your configuration and will get the same attribution to anyone who is a code owner for those files. In other words, this is a powerful way to compose your teams and manage ownership across a whole team of engineers.

Generate a CODEOWNERS file

Now that you have a config, you can generate a CODEOWNERS file:



pizza generate codeowners /path/to/your/git/repo

This will read the .sauced.yaml configuration file that you generated in your repo to know which git commit emails are associated with GitHub logins or teams.

The codeowners generation iterates the git-ref log and looks at the number of lines touched and the frequency of updates from individuals. It will find the top 3 codeowners per file who’ve done the most work within the configured time range (note: you can use the –range flag to change how far back to look in the git ref-log!)

We’re very excited to be bringing this tool to you! Knowing who owns what and how to get help from other teams can improve your workflow and minimize bottlenecks. Using tools that help you do that, can make it easier to connect with people when it matters most.

Be sure to check out the open source Pizza CLI repository for a full rundown of everything that’s possible with the Pizza CLI. And feel free to ask any questions or give us feedback in the GitHub issues!!

As always, stay saucy!

The Human Dependency Graph: Why We Need to Rethink Security in Open Source

BekahHW — Thu, 12 Sep 2024 13:44:12 +0000

"How many humans could screw up my dependency graph?"

This question, posed by Jordan Harband, provides a different perspective on open source security. In a recent episode of DevTools FM, Harband challenges the traditional metrics we use to evaluate open source security, suggesting that we've been looking at the wrong numbers all along.

We talk a lot about metrics, and what measures success in open source, but we often overlook the human element. Harband reminds us that behind every package, every line of code, there's a human being. When it comes to open source security, it's not about how many packages you're using—it's about how many people could potentially mess them up; it's about the "Human Dependency Graph."

The Problem with Counting Packages

Our fixation on easily quantifiable metrics like package counts mirrors a broader issue in open source: the tendency to prioritize speed over security. Sometimes we see a project with fewer dependencies and assume it's more secure. But that's not necessarily true. What if there's a high number of YOLO Coders pushing code directly to the main branch? What if the maintainers of those few packages are burnt out? What if those projects aren't following best practices?

Harband likens this obsession to outdated thinking from decades ago—"an absurd thing to care about." After all, what does the number of packages really tell you about the security of your project?

Harband's argument flips traditional understanding on its head. He argues that a company with 10,000 internal developers might actually be at greater risk than a project relying on 100 external open source maintainers. Why? Because each person with access to the code is a potential point of vulnerability, not because they're malicious, but simply because they're human and capable of making mistakes. Instead of simply counting packages or contributors, we need to evaluate the expertise, reliability, and interconnectedness of the human network behind our code.

However, we need to consider another factor here: the lottery factor. This concept suggests that a project becomes vulnerable if a small number of contributors (typically 2 or fewer) account for more than 50% of the contributions. So while having fewer maintainers might seem safer, it's not that simple. The ideal scenario balances a small group of supported and highly skilled maintainers to prevent over-reliance on any single individual. This view is at the heart of understanding the Human Dependency Graph.

The Real Threat: Focusing on the Wrong Metrics

Metrics like package size, issue count, and star rating, might seem to tell a clear story, but in reality can mislead us. Harband points out a startling possibility: "Somebody will make a package that's like 1K smaller solely so they can take over your supply chain."

In other words, if we remain laser-focused on reducing package size or maximizing star count, we could be opening ourselves up to security risks rather than mitigating them. The numbers we've been relying on don't just miss the point—they might be actively leading us astray.

A Call to Action: Focus on the Humans, Not the Packages

So, what can we do with this new understanding? Here are three key actions:

Map Your Human Dependency Graph: Start identifying who maintains the packages you rely on. Know the people behind the code—their track records, their reputations, and their patterns of contribution. (Check out our Repo Pages for your dependencies to identify maintainers.)
Build Relationships, Not Just Dependencies: Cultivate connections with the maintainers of your critical packages. Open source survives with community and trust, and being an engaged part of that community can help you reduce your security risks. (Learn how to make that process easier by creating a Workspace from SBOM.)
Shift Your Focus from Package to Publisher Count: Instead of worrying about how many packages you're using, think about how many maintainers have access to them. This shift in thinking helps you prioritize real risks and can make your projects more resilient in the face of threats.

The Big Picture: Evolving Our Thinking on Open Source Security

As the open source ecosystem has grown, the metrics that mattered years ago might no longer apply. Just as we've had to rethink what constitutes valuable contributions in the age of GitHub, we also need to rethink what constitutes security.

Jordan Harband's idea of the Human Dependency Graph challenges us to look beyond what's easy to measure and to think critically about what we should really care about. After all, in a world where a single human can introduce significant vulnerabilities into a project, the numbers that matter most aren't the ones you might think.

The Art of Effective Open Source Contribution

BekahHW — Thu, 29 Aug 2024 13:22:16 +0000

In his book "The Second Mountain," David Brooks talks about the journey from a life focused on personal success to one dedicated to community and service - our deepest fulfillment comes not from individual achievement, but from connection and commitment to others. It struck me that this concept also resonates deeply with the growth and adoption we're seeing — and need to continue cultivating — in the open source world.

The Two Mountains of Open Source

For many of us, we've defined open source as the first mountain. The first mountain is focused on personal achievement, recognition, and career advancement. It's about building a impressive GitHub profile, gaining stars on your repositories, or using open source contributions to land your dream job.

But there's a second mountain to climb — one that's about commitment to the community and shared progress. It's where the real magic of open source happens, and it's where we need to set our sights.

Connection in open source goes beyond collaboration. It's about creating a shared sense of purpose, building trust, and supporting a community where contributors are recognized for positive contributions. It's about having context and understanding the people behind the code.

In fact, in Evidence for a Collective Intelligence Factor in the Performance of Human Groups, the researchers concluded that connection creates a collective intelligence, where the groups's combined knowledge and problem-solving capabilities exceed individual efforts.

Extending this to tech, when developers connect, they don't just share code — they share ideas, challenges, and visions. This exchange sparks creativity and leads to breakthrough solutions that likely wouldn't happen in isolation. A connected community is more likely to engage in meaningful discussions about the implications of their work, and identify areas for improvement or growth. They're also more likely to resolve issues, know where to ask questions, and to be more productive.

Open source has the power to affect lives globally. But sometimes it can be hard to find that connection, to know the people behind the pull requests.

Despite the clear benefits of connection, the distributed nature of open source development can make it challenging to build these relationships. Contributors often work across different time zones, cultures, and backgrounds, rarely meeting face-to-face. The anonymity of usernames and the focus on code can sometimes obscure the human element that's needed to build collective intelligence.

Contributors as Connectors

This is where intentional effort from contributors becomes necessary. It's not enough to simply submit pull requests or report issues. To truly harness the power of collective intelligence and create impactful open source projects, contributors need to actively invest in understanding and connecting with the community they're part of.
This could involve:

Taking time to read and understand the project's history, goals, and culture
Actively participating in community discussions beyond just code-related topics
Reaching out to other contributors to learn about their experiences and perspectives
Offering help and support to new contributors, sharing knowledge gained from their own journey
Initiating or participating in community events and collaborative problem-solving sessions

Through these efforts, contributors can help create an environment where everyone feels valued not just for their code, but for their unique perspectives and experiences. This approach also helps address some of the long-standing challenges in open source, such as contributor retention. When people take the initiative to connect and create a sense of belonging, they're more likely to stick around. They're also more likely to invite others in.

A contributor-driven approach to connection can lead to more sustainable and resilient open source communities. Rather than relying solely on maintainers to facilitate connections, it distributes the responsibility across the entire community, creating a stronger, interconnected open source ecosystem.

Essentially, by taking the initiative to connect and understand, contributors aren't just improving code — they're actively shaping and strengthening the foundation of what makes open source projects. This shift from passive participation to active community building is can unlock more of the potential of open source collaboration.

The "See a Need, Fill a Need" Approach

But how does a contributor get started? One way contributors can engage more deeply is by adopting a "see a need, fill a need" mindset. This approach encourages proactive problem-solving and creates a culture of initiative and responsibility.

Consider how React's reconciliation algorithm came about — developers saw a need for more efficient DOM updates and filled it, significantly improving the library's performance. Or how Webpack was created to solve module bundling issues that many developers were facing.

But contributing effectively goes beyond just solving technical problems. It's about understanding the project's philosophy and aligning with its vision. Evan You, the creator of Vue.js and Vite, emphasizes this point in a recent Secret Sauce Episode:

So for example, we have a current core team member on Vue's side where he's super young, but the pull requests that he makes, the quality of the code, the way he organizes stuff, and the way he makes the certain decisions makes me feel like, okay, this is probably how I would do it if I were to do it myself. And that kind of just naturally builds trust. And if he keeps doing, you know, if the person repeats this pattern a few times, then the trust just kind of compounds. I'm like, okay, this guy knows what he's doing and I can trust him to make the right decisions, even if I'm not directly paying attention to it. And that's important, right? And I think it's, if you're a maintainer, you will, like different maintainers have different style of working on their projects, right? Like we would have different code preferences. We have different design philosophies on how the project should work. So usually a good contributor understands your preference, your philosophy very instinctively, intuitively. I think that alignment is very key, right? Some people can be really technically brilliant, but maybe they just disagree on almost everything with you. And they wouldn't become good contributors or team members, right? So it's like technical skill is not really the only factor here.

This approach shifts the focus from "What can I get out of this?" to "What can I contribute that the community needs?" This deeper level of engagement goes beyond technical proficiency, and creates a sense of alignment and trust within the community. When contributors invest time in understanding a project's ethos, they're not just writing code — they're becoming integral parts of the project's ecosystem. This approach leads to more meaningful contributions, smoother collaborations, and a stronger, more cohesive open source community. It exemplifies the "see a need, fill a need" philosophy in a broader sense, where the "need" isn't just a technical problem, but also includes the need for contributors who truly understand and align with the project's vision and values.

Building Trust Capital: The Currency of Open Source

While the "see a need, fill a need" approach is a great starting point, sustained and impactful contribution to open source projects requires more. It requires building what we call "trust capital" — a asset that's accumulated over time through consistent, quality interactions, and a deep understanding of the project's context.

Trust capital in open source communities is the confidence and credibility you earn through your contributions and interactions. It's not just about the code you write or the issues you solve; it's about how you engage with the community, respect its processes, and align with its goals. As Evan You pointed out, when a contributor consistently makes decisions that align with the project's philosophy, trust naturally builds and compounds over time. In a previous post, The Compound Interest of Open Source, we explored how contributions can have a compounding effect, leading to increased trust and recognition within the community.

But how do you build this trust capital? It starts with understanding the project's context:

Project History: Dive into past issues and pull requests to understand the project's evolution. (We're currently building a tool to connect you more granularly to the codeowners of a project to help you understand the project's history, so keep your eyes on our pizza-cli.)
Current Direction: Familiarize yourself with the project's roadmap and immediate goals.
Community Dynamics: Observe how decisions are made and who the key contributors are.
Maintainer Preferences: Understand the maintainers' coding style, design philosophy, and communication preferences.

As you work to understand a project's context and build trust capital:

Listen Actively: Pay attention to discussions, even on issues you're not directly involved in.
Ask Thoughtful Questions: Show your engagement and desire to understand.
Start Small: Begin with minor contributions as you build your understanding.
Respect Processes: Follow the project's contribution guidelines meticulously.

Every interaction is an opportunity to both learn and demonstrate your commitment to the project. This approach aligns perfectly with the "see a need, fill a need" philosophy we discussed earlier. You're not just filling technical needs, but also the need for contributors who truly understand and align with the project's vision and values.

Ascending the Second Mountain: The Summit of Open Source

The first mountain of open source might be about personal achievement: the thrill of seeing your code merged, the pride in solving a complex problem, or the boost to your resume. But the second mountain? That's where the true magic of open source happens.

This second mountain is about connection — not just to code, but to people, to purpose, and to a larger understanding of the projects, maintainers, and contributors. It's about understanding that every line of code is part of a larger story, a narrative written by a experts in different areas, with knowledge bases that shouldn't be siloed.

Remember Evan You's anecdote about the young Vue contributor? That contributor didn't just write good code — they demonstrated an intuitive understanding of the project's philosophy and the maintainers' preferences. They proved themselves to those who had already proven themselves.

This approach is far more effective than trying to brute-force your way into a community. It's not about making the loudest noise or the biggest splash. It's about thoughtful, respectful integration into an existing ecosystem.

Maximizing Software Security: The Benefits of Tracking SBOMs in Your Projects

BekahHW — Thu, 22 Aug 2024 18:14:54 +0000

Recently, Congressman Maxwell Alejandro Frost and Congressman Don Beyer introduced new legislation called "The Spacecraft Cybersecurity Act" that will require NASA to secure a cybersecurity protection plan from manufacturers applying to use federal dollars to build NASA spacecrafts. This legislation is a response to "thousands of cyberattacks from malicious actors, including state-sponsored threats from China and Russia, [that] have been launched against NASA, threatening the safety of Americans, including astronauts."

"As we enter a new era of cyber threats, establishing a reasonable timeline for NASA to incorporate cybersecurity measures into their acquisition process is more important than ever. The Spacecraft Cybersecurity Act would safeguard NASA's space missions and continue to advance our country's leadership in space exploration that contributes to our economy, security, and understanding of space." -Congressman Frost

This Act requires NASA to finalize a plan within 270 days of the law’s enactment to revise its spacecraft acquisition standards to incorporate important cybersecurity requirements. Recognizing the technical complexities of this task, the bill allows NASA’s experts time to develop this plan.

NASA's recent actions are not occurring in isolation. They're part of a broader trend of increased scrutiny on software supply chains, particularly in government and critical infrastructure sectors. As governments worldwide deal with increasing cyber threats, they're turning their attention to the backbone of modern software - open source. This shift is creating both challenges and opportunities for the open source community.

The Cyber Resilience Act (CRA)

While NASA's actions have brought immediate attention to the issue of software supply chain security, the European Union's proposed Cyber Resilience Act (CRA) represents a more comprehensive and far-reaching shift in the regulatory landscape. The CRA, first proposed in September 2022, aims to establish "common cybersecurity standards for products with digital elements across the EU."

Key Points of the CRA:

Scope: The CRA applies to all products with "digital elements," which includes software and potentially impacts a high number of open source projects.
Requirements: Manufacturers would need to implement security measures, conduct risk assessments, and provide ongoing support and updates for their products.
Reporting Obligations: The Act mandates reporting of actively exploited vulnerabilities and incidents to EU authorities within 24 hours.
Penalties: Non-compliance could result in fines of up to €15 million or 2.5% of "global annual turnover."

Why the CRA Matters for Open Source:

Global Impact: Although an EU regulation, the CRA's effects will be felt globally because of the interconnected nature of software supply chains.
SBOM (Software Bill of Material) Adoption: SBOMs may become more of a standard practice due to the CRA's requirements.
Open Source Implications: Initially, the open source community raised concerns about the CRA's potential to create a "chilling effect" on open source development. However, recent amendments have introduced the concept of an "open source steward" and provided some exceptions for open source software.
Preparation Time: With the CRA expected to come into effect within the next two years, the open source community has a limited window to prepare and adapt.

The CRA and SBOMs

The CRA doesn't explicitly mandate the use of SBOMs, but its requirements for security measures and transparency align closely with SBOM principles.

An SBOM, or Software Bill of Materials, is a detailed list of the software components and dependencies that make up a software application. It’s like an inventory or a “recipe” that outlines the different parts that have been used to create the software. SBOMs are useful for understanding the software supply chain, tracking vulnerabilities, and ensuring compliance with regulations like the CRA.

In OpenSauced, you can create SBOMS from a Repository Page. This feature allows you to generate a Software Bill of Materials (SBOM) for your open source project, providing a detailed inventory of all the software components and dependencies used in your application. For example, if I create an SBOM for Microsoft/TypeScript, I can see a list of 34 of it's dependencies, making it easier to track and manage the software supply chain.

Link to TypeScript SBOM

Implementing comprehensive SBOMs could help organizations as the CRA is enforced by allowing for:

Risk assessment of software components
Ongoing vulnerability management
Transparency in software composition
Facilitating incident reporting and response

Last Thoughts

The tightening focus on software supply chain security mark a crossroad for the open source community. This shift isn’t just a challenge — it’s a chance to lead in strengthening the security and transparency of open source projects. We need to find ways to build greater trust with users, understand regulatory demands, and ensure the continued success of our projects.

Generate and review the SBOMs for your projects to see how secure the projects you depend on are. When we understand the software supply chain, we can better prepare for the changing regulations and find ways to improve our projects security.

Supercharge Your GitHub Profile: Showcase Your Open Source Contributions

Nick Taylor — Mon, 19 Aug 2024 15:01:09 +0000

Last week, we launched our brand new Dev Cards with the OSCR (Open Source Contributor Rating) highlighted on the front to make it easier for you to showcase your impact in open source. To make it even easier, I've cooked up a little GitHub Action that'll automatically update your Dev Card on your GitHub profile.

In this post, we're gonna dive into what Dev Cards are all about, how this new GitHub Action works, and how you can get it set up.

OpenSauced Dev Cards

At OpenSauced, we created dev cards to showcase your open source stats.

We also recently introduced the OSCR score which appears prominently on dev cards now.

Introducing the OSCR: Celebrating Open Source Stars

BekahHW for OpenSauced ・ Aug 13 '24

#opensource

If you head on over to your OpenSauced profile page, you can see your dev card now. Here's my OpenSauced profile. There's a little pizza card button you can press to see it.

The card is interactive and can be flipped.

Introducing the OpenSauced Dev Card GitHub Action

To make it easier to showcase your contributions, I've developed a GitHub Action that automates the process of fetching your OpenSauced dev card (static version) and updating it in your GitHub profile README.

nickytonline / open-sauced-dev-card-action

A GitHub Action that automatically fetches and updates an OpenSauced dev card image for a specified GitHub user. It runs on a schedule or manual trigger, saving the image to the user's profile README repository for easy display.

OpenSauced Dev Card GitHub Action

This project fetches the OpenSauced dev card for an OpenSauced user with the GitHub username specified in the GitHub action.

About the OpenSauced Dev Card

Usage

To use this action, you need to add the following to a GitHub Actions workflow file.

name: Update OpenSauced Dev Card

on:
  schedule:
    - cron: "0 0 * * *" # Run daily at midnight UTC
  workflow_dispatch: # Allow manual triggering

jobs:
  update-dev-card:
    runs-on: ubuntu-latest
    steps:
      - name: Update Dev Card
        uses: nickytonline/open-sauced-dev-card-action@v1.0.0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          username: "your_username"

We suggest you add this to a workflow file in the .github/workflows directory of your repository and call it something like update-open-sauced-dev-card.yml.

When the…

View on GitHub

This means you can have an always up-to-date representation of your open source contributions from OpenSauced stats right on your GitHub profile.

Here's mine on my GitHub profile

How It Works

The action runs on a schedule (default is daily at midnight UTC) or can be triggered manually.
It fetches your dev card image from OpenSauced.
The image is saved to your profile README repository.
Your README is automatically updated with the new image.

Setting It Up

View the GitHub action on the GitHub Action Marketplace

To use this action in your own GitHub profile, follow these steps:

Create a workflow file (e.g., .github/workflows/update-open-sauced-dev-card.yml) in your profile README repository.

Add the following content to the file:

name: Update OpenSauced Dev Card

on:
  schedule:
    - cron: "0 0 * * *" # Run daily at midnight UTC
  workflow_dispatch: # Allow manual triggering

jobs:
  update-dev-card:
    runs-on: ubuntu-latest
    steps:
      - name: Update Dev Card
        uses: nickytonline/open-sauced-dev-card-action@v1.0.2
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          username: "your_username"

Replace "your_username" with your actual GitHub username.
Add the following markdown to your README.md:
```
[![My OpenSauced Dev Card](./dev-card.png)](https://oss.fyi/your_username)
```
Again, replace your_username with your actual GitHub username.
Run the GitHub action manually the first time if you want to get an initial image. It's not a big deal if you don't, but it'll mean the image will look broken until the first time the action runs at midnight UTC.

Making the Most of Your Dev Card: Tips & Tricks

If you want to make the most of your dev card on your GitHub profile? Here are some tips:

Prime Real Estate: Place your card where you think it will be noticed on your README. First impressions count, and you want visitors to see your open source contributions. Maybe place it between your "About Me" and your "Current Projects" for a well-rounded profile.
Context is Key: Don't just leave your card hanging there. Add some text to introduce it. Something like: "Check out my open source contribution snapshot!"

The Secret Sauce: Understanding Your OSCR Score

Think of the OSCR as your open source score that looks at:

Your contribution frequency
The quality of your contributions
Your ability to start and be a part of open source conversations

Your OSCR score provides a quick snapshot of your open source activity and impact. It gives people an idea of how active and influential you are in the open source community.

Like any metric, your open source experience is about more than just one number.

Conclusion

Open source contributions are a fantastic way to grow as a developer and give back to the community. With this GitHub Action and OpenSauced, you can easily showcase your efforts and inspire others to get involved.

Give it a try and let me know what you think!

Stay saucy peeps!

If you would like to know more about my work in open source, follow me on OpenSauced.