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.

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.

You can check it out here

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​

1. The action runs on a schedule (default is daily at midnight UTC) or can be triggered manually.
2. It fetches your dev card image from OpenSauced.
3. The image is saved to your profile README repository.
4. 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:

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

2. 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"
   

3. Replace "your_username" with your actual GitHub username.

4. 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.

5. 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.

But there’s a catch: before the CRA, companies providing or distributing software would often need to take on much of the risk when ensuring safe and reliable software was being shipped to end users. Now, software maintainers further down the supply chain will have to carry more of that weight. Not only may certain open source maintainers need to meet certain requirements, but they may have to provide an up to date security profile of their project.

As the Linux Foundation puts it:

The Act shifts much of the security burden onto those who develop software, as opposed to the users of software. This can be justified by two assumptions: first, software developers know best how to mitigate vulnerabilities and distribute patches; and second, it’s easier to mitigate vulnerabilities at the source than requiring users to do so.

There’s a lot to unpack in the CRA. And it’s still not clear how individual open source projects, maintainers, foundations, or companies will be directly impacted But, it’s clear that the broader open source ecosystem needs easier ways to understand the security risk of projects deep within dependency chains. With all that in mind, we are very excited to introduce the OpenSSF Scorecard ratings within the OpenSauced platform.

What is the OpenSSF Scorecard?​

The OpenSSF is the Open Source Security Foundation: a multidisciplinary group of software developers, industry leaders, security professionals, researchers, and government liaisons. The OpenSSF aims to enable the broader open source ecosystem “to secure open source software for the greater public good.” They interface with critical personnel across the software industry to fight for a safer technological future.

The OpenSSF Scorecard project is an effort to unify what best practices open source maintainers and consumers should use to judge if their code, practices, and dependencies are safe. Ultimately, the “scorecard” command line interface gives any the capability to inspect repositories, run “checks” against those repos, and derive an overall score for the risk profile of that project. It’s a very powerful software tool that gives you a general picture of where a piece of software is considered risky. It can also be a great starting point for any open source maintainer to develop better practices and find out where they may need to make improvements. By providing a standardized approach to assessing open source security and compliance, the Scorecard helps organizations more easily identify supply chain risks and regulatory requirements.

OpenSauced OpenOSSF Scorecards​

Using the scorecard command line interface as a cornerstone, we’ve built infrastructure and tooling to enable OpenSauced to capture scores for nearly all repositories on GitHub. Anything over a 6 or a 7 is generally considered safe to use with no blaring issues. Scores of 9 or 10 are doing phenomenally well. And projects with lower scores should be inspected closely to understand what’s gone wrong.

Scorecards are enabled across all repositories. With this integration, we aim to make it easier for software maintainers to understand the security posture of their project and for software consumers to be assured that their dependencies are safe to use.

Starting today, you can see the score for any project within individual Repository Pages. For example, in kubernetes/kubernetes, we can see the project is safe for use:

Let’s look at another example: crossplane/crossplane. These maintainers are doing an awesome job of ensuring they are following best practices for open source security and compliance!!

The checks that the OpenSSF Scorecard looks for involves a wide range of common open source security practices, both “in code” and with the maintenance of the project: e.g. checking for code review best practices, if there are “dangerous workflows” present (like untrusted code being run and checked out during CI/CD runs), if the project is actively maintained, the use of signed releases, and many more.

The Future of OpenSSF Scorecards at OpenSauced​

We plan to bring the OpenSSF Scorecard to more of the OpenSauced platform, as we aim to be the definitive place for open source security and compliance for maintainers and consumers. As part of that, we’ll be bringing more details to the OpenSSF Scorecard with how individual checks are ranked:

We’ll also be bringing OpenSSF Scorecard to our premium offering, Workspaces:

Within a Workspace, you’ll soon be able to get an idea of how each of the projects you are tracking stack up alongside each other's score for open source security and compliance. You can use the OpenSSF Score together with all the Workspace insights and metrics, all in one single dashboard, to get a good idea of what’s happening within a set of repositories and what their security posture is. In this example, I’m tracking all the repositories within the bottlerocket-os org on GitHub, a security focused Linux based operating system: I can see that each of the repositories has a good rating which gives me greater confidence in the maintenance status and security posture of this ecosystem. This also enables stakeholders and maintainers of Bottlerocket to have a birds eye snapshot of the compliance and maintenance status of the entire org.

As the CRA and similar regulations push more of the security burden onto developers, tools like the OpenSSF Scorecard become invaluable. They offer a standardized, accessible way to assess and improve the security of open source projects, helping maintainers meet new compliance requirements and giving software consumers confidence in their choices.

Looking ahead, we're committed to expanding these capabilities at OpenSauced. By providing comprehensive security insights, from individual repository scores to organization-wide overviews in Workspaces, we're working to create a more secure and transparent open source ecosystem, to enable anyone in the open source community to better understand their software dependencies, feel empowered to make a meaningful change if needed, and provide helpful tools to open source maintainers to better maintain their projects.

Stay saucy!

Let's start with a personal story. When I first thought of contributing to an open source project, I was afraid. The fear of making a mistake in front of the entire internet was overwhelming. Sound familiar? If so, you're not alone. Research shows that this fear of public failure is a significant barrier to open source participation.

But here's the interesting part: studies also show that the most effective way to overcome this fear is through community support. When we're part of a group, our fear of failure decreases, and our willingness to take risks increases. This is where the magic happens.

#100DaysOfOSS Challenge​

Our #100DaysOfOSS Challenge, isn't about coding for 100 days. It's about leveraging the power of community to transform hesitation into action.

Here's why I think this approach works:

1. Structured Progress: The challenge provides a clear pathway, breaking down contributing to open source into manageable weekly tasks.

2. Community Support: By connecting participants, the challenge creates a supportive peer group. This not only can reduce anxiety but also increase accountability and motivation.

3. Learning by Doing: The challenge emphasizes practical contributions, aligning with the principles of experiential learning - you don't have to know how to code to contribute.

4. Flexibility: Participants can tailor the challenge to their interests, which research shows increases intrinsic motivation and long-term engagement.

This year, we have support from GitHub Education to enhance the challenge and we're introducing weekly structured posts and increased community engagement opportunities. It's an experiment in scaling the benefits of community-supported learning.

So, here's my call to action: If you've ever been curious about open source but hesitated to jump in, join us for #100DaysOfOSS with your intro today - we already have over 100 people!

P.S. If you're participating, you can also sign up for the OpenSauced newsletter for biweekly updates on Open Source topics to help you along your journey.

What is useRef?​

The useRef hook creates a reference object that holds a mutable value, stored in its current property. This value can be anything from a DOM element to a plain object. Unlike component state via say the useState hook, changes to a reference object via useRef won't trigger a re-render of your component, improving performance.

Examples​

Referencing a DOM element using the useRef Hook​

In React, state manages data that can trigger re-renders. But what if you need a way to directly access document object model (DOM) elements that shouldn't cause re-renders? That's where the useRef hook comes in.

Typically, you'd do something like this.

import { useEffect, useRef } from "react";

export const SomeComponent = () => {
  const firstNameInputRef = useRef<HTMLInputElement>(null);

  // for plain JavaScript change the above line to
  // const firstNameInputRef = useRef(null);

  useEffect(() => {
    firstNameInputRef.current?.focus();
  }, []);

  return (
    <form>
      <label>
        First Name:
        <input type="text" ref={firstNameInputRef} />
      </label>
    </form>
  );
};

1. We create a variable named firstNameInputRef using useRef to reference the DOM element (initially null) and use useEffect to focus the input element on the initial render.
2. Inside useEffect, we check if firstNameInputRef.current exists (it will be the actual DOM element after the initial render). If it does, we call focus() to set focus on the input.

Referencing a non-DOM element using the useRef Hook​

Recently, I was working on OpenSauced's StarSearch, a Copilot for git history feature we released at the end of May 2024. You can read more about StarSearch in We Made a Copilot Tool for you to Unlock the Power of Git History.

The ask was to be able to start a new StarSearch conversation. To do so, I had to stop the current conversation. If you've worked with the OpenAI API or similar APIs, they typically return a ReadableStream as a response.

A ReadableStream is a web API that allows data to be read in chunks as it becomes available, enabling efficient processing of large or real-time data sets. In the context of API responses, this means we can start handling the data immediately, without waiting for the entire response to complete.

I initially had this feature working, but ran into issues if the response started to stream. The solution, create a reference to the readable stream via the useRef hook and when a new conversation is started, cancel the one in progress. You can see these changes in this pull request (PR), fix: now a new StarSearch chat can be started if one was in progress.

So now, if someone presses the Create a New Conversation button, I cancel the current streaming response from StarSearch, e.g.

  const streamRef = useRef<ReadableStreamDefaultReader<string>>();

  // for plain JavaScript change the above line to
  // const streamRef = useRef();
...

  const onNewChat = () => {
    streamRef.current?.cancel();
    ...
  };

...

1. We create a variable named streamRef using useRef to hold a reference to the current ReadableStreamDefaultReader.
2. The onNewChat function checks if streamRef.current exists (meaning a stream is ongoing).
3. If a stream exists, we call cancel() on streamRef.current to stop it before starting a new conversation.

Wrapping Up​

useRef was the perfect solution for my use case. Maybe you'll find the useRef hook useful for something other than referencing a DOM element as well.

You can store almost anything in a reference object via the useRef hook, and it won't cause re-renders in your component. If you're persisting component state, opt for useState or other hooks like useReducer so that the component does re-render.

For further reading on the useRef hook, I highly recommend checking out the React documentation for the useRef hook.

Stay saucy peeps!

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

The history of Valibot​

If video is your jam, check out this highlight from the live stream that summarizes the history of Valibot.

During his thesis work, developer Fabian Hiller found himself with dedicated time to pursue an idea he'd been mulling over - creating a new modular data validation library for JavaScript. This led to the birth of Valibot.

Fabian had previously worked on Modular Forms, but he wanted to bring that same modular philosophy to data validation. While popular validation libraries like Zod offer excellent APIs, Fabian felt there was room to take modularity even further.

"For Zod, it doesn't make sense to make it extremely modular as Valibot, because most Zod users love Zod for its API", Fabian explained. "This would probably be too big of a breaking change."

Instead of trying to rebuild Zod from the ground up, he decided a fresh start made more sense. Valibot aims for ultimate modularity, allowing developers to compose small, reusable validation units together.

Fabian didn't work in isolation. He reached out to Zod's creator Colin McDonnell, but the timing didn't line up for deeper collaboration initially. Fabian remains in touch with McDonnell and other open source maintainers though.

"I'm sure improvements I made in Valibot will hopefully improve other libraries, and other libraries will hopefully affect and improve Valibot," he said. "I hope at the end we end up with great open source projects, and the community can choose what they prefer."

With Valibot, Fabian hopes to provide developers a new, composable approach to data validation. And by cross-pollinating with other libraries, he aims to push the entire JavaScript validation ecosystem forward.

A First Look at Valibot​

If you want to experiment with Valibot, I recommend you check out the Valibot playground. Fabian actually made a change to enable prettier support after our live stream! 🤩

Also, version 0.31.0 was recently released with a whole rework of the API.

Let's start of simple. We want to create an e-mail validator. Valibot makes this pretty easy for us.

import * as v from "valibot";

const EmailSchema = v.pipe(v.string(), v.email());

const validEmail = v.safeParse(EmailSchema, "jane@example.com");

console.log(validEmail);

First, we import the Valibot package. Next, we create a schema for a valid email, const EmailSchema = v.pipe(v.string(), v.email());

v.pipe is so powerful. It allows us to chain validators. First, we check that the input is a string via v.string(), and next, if it's a valid email via v.email().

If you run this in the playground, you'll get the following output.

[LOG]: {
  typed: true,
  success: true,
  output: "jane@example.com",
  issues: undefined
}

You can view the following example in this Valibot playground.

Let's see what happens when we have an invalid email.

import * as v from "valibot";

const EmailSchema = v.pipe(v.string(), v.email());

const validEmail = v.safeParse(EmailSchema, "janeexample.com");

console.log(validEmail);

If we run the updated playground, it will now output the following:

[LOG]: {
  typed: true,
  success: false,
  output: "janeexample.com",
  issues: [
    {
      kind: "validation",
      type: "email",
      input: "janeexample.com",
      expected: null,
      received: "\"janeexample.com\"",
      message: "Invalid email: Received \"janeexample.com\"",
      requirement: RegExp,
      path: undefined,
      issues: undefined,
      lang: undefined,
      abortEarly: undefined,
      abortPipeEarly: undefined
    }
  ]
}

You can view the updated example in this Valibot playground.

You can see an example of valibot in action in a recent pull request of mine.

if (context.query.id) {
  try {
    sharedChatId = parseSchema(UuidSchema, context.query.id);
    searchParams.set("id", sharedChatId);
  } catch (error) {
    captureException(
      new Error(`Failed to parse UUID for StarSearch. UUID: ${sharedChatId}`, {
        cause: error,
      })
    );
    throw new Error("Invalid shared Chat ID");
  }
}

Contributing to Valibot​

Valibot is open source, like many things in the JavaScript ecosystem.

The project has a low lottery factor, and it also has high contributor confidence (many stargazers and forkers come back later on to make a meaningful contribution).

If you're looking to contribute to open source in the JavaScript/TypeScript ecosystem, Valibot might be up your alley.

Wrapping Up​

We only scratched the surface of Valibot, but I encourage you to check it out. Valibot was highlighted in the latest bytes.dev issue, VALIBOT AND THE CIRCLE OF LIFE. You know a library is gaining traction if bytes.dev covers it!

Stay saucy peeps!

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

Start by Building Something You Need​

When you build something for yourself, you develop a deeper understanding of your own goals, requirements for a project, and how to solve specific problems.

When you're building for yourself, you become more familiar with the complexity of coding, problem-solving, and project management. Building your own project first also teaches valuable lessons in ownership and responsibility. You learn to see a project through from conception to implementation, and how to approach the challenges that come up along the way. What you learn from this experience will help you approach open source contributions with the right mindset and make informed and thoughtful contributions to projects that benefit their communities.

You'll learn more about how to align your efforts with the needs of the project and its users, which ultimately leads to a more rewarding and effective contribution experience.

Understand Your Skills and Interests​

Working on your open projects can help you better understand your skill-level and what you have the ability to take on. It’s so important to understand, in fact, that I wrote a whole post on it: How to Assess Your Skill Level Before Contributing to Open Source.

Once you have a good understanding of your skill level, you can better assess your ability to make meaningful contributions. If you’re a beginner, don’t take on a complicated issue that requires more experience. Likewise, if you are an experienced programmer, don’t take an issue that’s meant for someone in their early career stages.

Use Open Source Software​

Scouring the internet for a project to submit a one-off Pull Request (PR) to decreases your connection to the project and your desire to see it be successful. In a recent Open Source Friday Stream with @ladykerr and @bdougieyo, Jan Ainali pointed out that it's "much better [is] to contribute to something you use and where you would like to see an improvement."

When you are invested in a project, you’re more likely to navigate challenges, ask meaningful questions, and to grow and progress. The more you use a product, the better contributor you’ll be, because you have a depth of understanding that helps you identify what’s useful for a project and its community. Using open source software gives you access to opportunities to create bug reports or ask for new features because you understand the project and the user's expectations for the project. Giving feedback is a valuable contribution.

Find an Open Source Community​

When you're part of a community, you get access to insider information about the project. Listening in those communities, allows you to engage with the creators of the open source project. This is your opportunity to learn, understand, and grow. You can hear Kelsey Hightower talk about community here. Being involved in the community also gives you the context you need to create meaningful contributions, decreases the barrier to entry, and allows you to understand the type of project and support that you’ll be offered if you contribute to their projects.

When you are involved in a community, you are more likely to be driven by a genuine need to improve the software, which leads to more useful contributions. This mindset shift from self-improvement to community improvement not only benefits the open source project but also helps to create a more collaborative and supportive open source community.

Talk to Other Open Source Contributors​

Connecting with other contributors can be an important step in becoming an informed and effective community member. When you engage with them in their communities, follow them on social media, or interact with their content (reading and commenting on their blog posts, watching or commenting on their videos, listening to their podcasts, etc.), you can gain valuable insights into the open source ecosystem and the specific needs of the project. Understanding the pain points and how contributors discuss and address the issues helps you to avoid adding more work for the maintainers and instead becoming a positive force in the project.

Being well-informed about the community dynamics and project challenges means that your contributions are more likely to be meaningful and well-received. It also means you'll be better equipped to offer solutions that align with the project's goals and the community's expectations.

Additionally, tools like StarSearch can help you identify key contributors to projects you're interested in. By finding those with overlapping experience or expertise, you can connect with the right people and build meaningful relationships.

Look for Project Tags and Labels​

Once you've created your own projects, used and learned about the project you're interested in contributing to, and joined and participated in the community, you can start looking at the issues to see if they're a good fit for your first contribution. Many open source projects use tags and labels like "good first issue" to indicate tasks that are suitable for beginners. These tags make it easier to find issues that match your skill level and provide a clear entry point for contributing.

Write Your Own Issue​

Remember, good first issues don’t exist; the best issue for you is probably the one that you write yourself.

Takeaways​

Contributing to open source shouldn't be about checking the box of things to do if you're an early career developer. It should be about making a meaningful contribution to a project that improves the project for all users. This will also go a long way towards making valuable and recognized contributions.

Understanding your skill level will help you choose the right tasks, decrease frustration, and guide your open-source journey. In this blog post, we'll explore why assessing your skill level is important and provide a personal inventory to help you evaluate your abilities.

Why It's Important to Assess Your Skill Level​

Understanding your strengths and weaknesses allows you to be more efficient, set realistic goals, and find the right open-source project to contribute to. Additionally, accurately identifying your skill level will allow you to match issues to your abilities, creating an experience that leads to confidence and productivity and prevents you from feeling overwhelmed.

Defining Skill Levels​

Before we go into the questions, let’s define different skill levels to help you as we inventory.

Beginner​

Beginners have a basic understanding of a programming language or technology but don’t have practical experience. You might have used the language in tutorials or simple exercises but haven't implemented it in a real project.

• Example: You know the syntax of Python and can write basic scripts, but you haven't built a complete application yet.

Intermediate​

Intermediate developers have practical experience and can work on projects independently. You understand core concepts and have implemented them in real-world scenarios, but you might need guidance for more complex tasks.

• Example: You have built web applications using JavaScript and a framework like React, but you still look up advanced features or best practices.

Advanced​

Advanced developers have deep expertise and can handle complex tasks with confidence. You have extensive experience, contribute to architectural decisions, and often mentor others.

• Example: You have several years of experience with Java, have built and maintained large-scale applications, and are comfortable with advanced topics like concurrency and optimization.

Personal Inventory: General Questions​

Understanding your general experience helps lay the foundation for assessing your skill level. This section focuses on your overall exposure to software development, helping you gauge your position in the broader landscape.

1. What programming languages are you most comfortable with?
2. How many years of experience do you have with software development?
3. Have you ever contributed to any open source projects before? If yes, which ones and what types of issues have you contributed to?
4. How frequently do you code (daily, weekly, monthly)?
5. What types of projects have you worked on in the past (web development, data science, mobile apps, etc.)?

Technical Skills​

Evaluating your technical skills provides a clearer picture of your capabilities in specific languages and tools. These questions help you pinpoint your strengths and identify areas for improvement, to help you find tasks that align with your expertise level.

1. How would you rate your proficiency in your most-used languages/technologies (Beginner, Intermediate, Advanced)?
2. Which development tools and environments are you familiar with (Git, Docker, VS Code, etc.)?
3. Are you familiar with version control systems like Git? If yes, how proficient are you?
4. How comfortable are you with debugging and troubleshooting code?
5. Have you worked with any frameworks or libraries? If yes, which ones (e.g., React, Angular, Django, Flask) and how would you rate yourself (Beginner, Intermediate, Experienced)?
6. Are you familiar with the process of contributing to open source projects (reading contributing guidelines, taking issues, branching, writing meaningful commit messages)?

Core Skills and Collaboration​

Because so much of open-source work is asynchronous, good core skills are important for effective collaboration and communication within open-source communities. The questions below assess your ability to work with others, understand code written by different developers, and contribute positively to the team.

1. How comfortable are you with reading and understanding other people's code?
2. Have you ever participated in code reviews? If yes, how often?
3. How do you typically approach problem-solving in your projects?
4. How comfortable are you with writing documentation for your code?
5. Have you ever mentored or taught others in programming or related subjects?

Project Management and Organization​

Effective project management skills help you stay organized and productive. Understanding how to prioritize tasks, manage time, and use project management tools (like GitHub projects) is helpful when contributing to open source projects, especially because of multiple contributors.

1. Have you ever managed or led a software project? If yes, what was your role?
2. How do you prioritize tasks and manage your time when working on projects?
3. Are you familiar with any project management tools? If yes, which ones?
4. How do you track and stay updated with the latest developments in tech?

Learning and Development​

Continuous learning is an important part of being in tech because it allows you to stay relevant and improve your skills. These questions should help you reflect on your learning habits and identify opportunities for growth.

1. How do you usually learn new programming languages or technologies (online courses, books, tutorials)?
2. Have you ever completed any online courses? If yes, which ones?
3. How comfortable are you with learning new technologies and adapting to changes?
4. What are your current learning goals or areas you want to improve in?
5. Where do you first turn when you want to learn something new (documentation, looking at other projects, etc.)?

Now that you’ve taken the inventory, you can more strategically approach open source contributions. Here’s how you can use this self-assessment to shape your approach practically:

• Set Realistic Goals: Based on your skill level, set achievable goals. If you’re a beginner, start with smaller tasks labeled “good first issue.” You also might find that you’re not ready to contribute to open source. That’s ok. Work on the skills you need to make your first contributions. This includes things like reading directions, paying close attention to your work, knowing how to ask questions when you’re stuck, etc. If you’re intermediate or advanced, look for more challenging tasks that help you build your network, solve a problem, or grow your skills.
• Choose the Right Projects: Use your assessment to select projects that align with your interests and expertise. Beginners might start with projects that have clear documentation and active communities - our Intro to Contributing Course is a good place to start if you’re ready to begin contributing. More experienced contributors can find complex projects that require deeper technical knowledge.
• Focus on Learning and Development: Identify the areas where you need improvement and seek out resources to fill those gaps. This could be online courses, tutorials, or even mentorship within the open-source community. For example, if you’re not familiar with git, you should find resources to help you learn before committing to an open-source issue.
• Engage with the Community: Understanding your collaboration skills can help you better engage with the open-source community. Participate in discussions, attend community events, and contribute to code reviews. You’ll be able to improve your skills and build valuable connections.
• Improve Project Management Skills: Use project management tools to organize your contributions effectively. Prioritize your tasks, set deadlines, and track your progress. This will help you manage your time better and contribute more efficiently.
• Seek Feedback and Iterate: Use your self-assessment as you seek feedback from project maintainers and other contributors so you can continuously improve and adapt your approach to contributions.

These practical steps can help you to leverage your self-assessment to make meaningful contributions to open-source projects and to create a positive impact on the open-source community. Happy contributing!

The Challenge of Open Source Connections​

Imagine you're at a tech company using cutting-edge technology. You need to upstream some important changes to ensure future compatibility but you find yourself hitting a wall. Who exactly should you reach out to? Who are the key contributors with the right expertise? Traditionally, this process would involve a lot of guesswork and detective work, looking through commit histories or issue discussions. Enter StarSearch, designed to change how we discover and connect with others in the open-source universe. With StarSearch, in just a few clicks, you’re able to identify key contributors skilled in that technology and maintainers who may have the answers you need. StarSearch isn’t just a tool; it’s your entry point into a more intimate, interconnected open-source community.

Introducing StarSearch​

StarSearch leverages advanced analytics and AI, all fueled by real-time data from GitHub Events. StarSearch isn’t just about identifying who committed what; it’s about understanding the dynamics and interactions within the open source community.

We’re live on Product Hunt! Join the conversation and share your thoughts.

Connecting with StarSearch​

Here’s how StarSearch addresses some of the common queries and needs within the community:

• What type of pull requests has {username} worked on?
• Who are the best developers that know {technology} and are interested in {technology}?
• Who are the most prevalent contributors to the {technology} ecosystem?
• Show me the lottery factor for contributors in the {repository} project?

These questions can be the starting point for building stronger projects and communities, allowing us to find people with passion and expertise that we may have never connected with before.

Learn More About StarSearch​

You can check out more about our approach and process, as well as the resources:

• Building a Copilot for Git History with pgvector and Timescale
• How We Saved Thousands with Open Source AI Technologies
• Meet StarSearch: Your New Open Source Navigator
• StarSearch Docs

Watch our "What is StarSearch" Video​

The Future of StarSearch​

StarSearch provides a nuanced view of the open-source landscape. It’s more than a tool; it’s a new way to navigate the open-source ecosystem, bringing clarity, connections, and community to our tooling and making the open source ecosystem feel more like a tightly knit community where everyone knows your name – and your code. And we're just getting started. We have big plans for the future of StarSearch.

If you’re ready to find a new way to connect, sign up for OpenSauced and be among the first to explore the future of open-source collaboration with StarSearch today.

Do we need Open Source Insights into Issues and Pull Requests?​

While GitHub provides a wealth of data on issues and PRs (pull requests), a high-level overview can give us a better understanding of what’s happening. Let’s take a closer look at what’s been happening at CRA.

Understanding Issues​

With a high-level overview of the recent issues, we can get a better idea of how to triage and prioritize. Let’s take CRA, for example.

A couple of things stand out:

Variety and Volume of Issues​

The issues within CRA range from security vulnerabilities to user experience complaints. The recent security issues identified (tagged with CVE identifiers) point to a critical need for security updates, with user experience issues like configuration problems that might be solved by improved documentation.

Frequency of Issues​

A high frequency of new issues can be a double-edged sword—it might show an active and thriving community, or it could indicate problems with user experience and documentation. Likewise, a low frequency of issues could indicate a stable project or a dying project. In the last 30 days, CRA has had a total of 9 open issues and 10 closed issues.

Community Interaction​

The level of interaction within issue discussions can reveal a lot about the community’s health and the project's transparency. Sure, stars and forks can help us understand the activity level of the project, but they’re not always the most telling.

How are contributors interacting with the maintainers, and how are maintainers communicating to them? Sometimes the most revealing issues are the ones asking if a project is still supported, like this one from almost a year ago.

Taking a closer look at the variety and volume of issues, how often they pop up, and how everyone's talking things through really tells us what needs immediate attention and what can wait. This overview can help maintainers figure out the best steps forward—whether it’s jumping on a hot issue, scheduling something for a later fix, or just keeping the lines of communication open with the community on the status of your project.

Understanding Pull Requests​

Issues don’t tell the whole story though. PRs help us to understand the vision of the project, the maintainers priorities, and the time that’s being put into the project.

Here are some of the things we learn about CRA:

Look at the State​

Over the last year, there have been 113 opened PRs and 2 merged. In fact, to find when the last PR was merged, we have to go back to almost a year ago, with all other PRs "Open" or "Closed" (without merge).

Size and Scope​

Pay attention to the number of changed files and the number of lines added/deleted. In healthy open-source projects, large PRs likely introduce new features or substantial changes, while smaller PRs might be bug fixes or documentation updates. Ideally, you’ll have a mix of sizes and give you a sense of the project's priorities and development lifecycle. Recently, with CRA, we see mostly very small fixes with under ten changes. In other words, there’s low activity on the repository when looking at PRs.

Freshness​

Another indicator of project health is how recently PRs were updated, created or closed. For a hugely popular project like CRA ( 102k stars, 26.6k forks, 1.9k watching), we’d expect a lot of activity, but, instead, we’re seeing little to no changes, even with simple fixes like updating a broken link.

Leveraging Open Source Insights for Strategic Decisions​

The real power in these insights is that it allows us to be more strategic about our decisions, ultimately increasing our productivity, allowing us to:

• Allocate resources more efficiently, prioritizing high-impact tasks.
• Enhance the community’s involvement by addressing the most pressing concerns promptly.
• Predict potential bottlenecks and prepare solutions in advance.

We've explored how PRs and Issues can unlock a deeper understanding of Create React App. But maybe the real question is: Can this approach be applied to predict future trends in the React ecosystem itself? Think about it. By analyzing the types of feature requests and bug fixes, can we get a glimpse into the challenges and pain points that developers are facing? Can we use what we see in our own projects and compare that to the ecosystem to get a better understanding of how we can succeed? There's no answer yet, but the future is there.

I think it’s safe to say we can pour one out for Create React App, but what’s next, then?

Like most things in tech, I think the answer is it depends. The closest replacement might be using Vite with a React Template, but there are more options to consider on this list. None are an exact replacement for CRA, but they are options that can get you up and running for simple single page apps to more complex full-stack projects.

What would you add to this list? Laravel, maybe 😉

If you are interested in better metrics for measuring open-source success, consider creating a workspace or explore the CRA Workspace I used to write this post.

If you want to learn more about becoming an open source maintainer, best practices, and tips and tricks for enhanced productivity and community collaboration, check out our new “Becoming a Maintainer” Course

The Maintainer Learning Curve​

When I started maintaining my first project, it wasn’t super popular, but I had enough contributors to feel overwhelmed. I didn’t have all the answers, my issues weren’t perfect, and I wasn’t sure what direction the project was going. Don’t get me wrong, it was a great experience and I formed bonds that I couldn’t have otherwise, but I could have been better prepared. I could’ve thought about how I would showcase the roadmap that was in my head. I could have written clearer issues. And I’m sure I could have made things easier on myself as I supported a lot of brand new contributors to a React Native repository.

This isn’t a unique story. There are many new open source projects popping up every day. Some maintainers have prepared for that launch, others are just trying something new, and others suddenly find their personal project gaining interest beyond what they ever imagined. But if you’re not prepared, you can feel overwhelmed by the responsibilities really quickly especially with a lack of structure support and without mentorship. The good news is that it’s ok, and you can still succeed. Take Liyas Thomas, the founder of Hoppscotch who started the project as a way to solve a problem he was facing and to enhance his resume. Not only is his project still going, but he’s now the CEO of that passion project.

We don’t want you to feel alone. We want you to have a success story too and to make sure new maintainers feel supported and understand the nuances of being a maintainer. This is why we created our “Becoming a Maintainer” Course and have Category in our Community for folks who have taken our courses. We want you to be supported and to be able to network with contributors. We want to make sure if you have questions, we can find you answers.

Growing as a New Maintainer​

It can feel like a big leap from contributor to maintainer, but it doesn’t have to be. One of the top challenges is realizing that as a maintainer, your role is utility player: you’re often writing code, creating issues, managing projects, engaging with your growing community, and leading a whole project. In essence, you’re nurturing a project, ensuring the code and quality, supporting the community, and providing direction.

There’s a difference between becoming a maintainer for an existing project, and becoming a maintainer for a new project. You’re more likely to have support, mentorship, and some sort of strategy or map if you’re coming into an existing project. But when you’re coming into or starting a new project, you’re developing your own map, finding the tools that you’ll need for the journey, and navigating through unknown terrain. But you don’t have to be on that journey alone.

Utilize the resources available to you, reach out to other maintainers, and find seasoned contributors who are willing to provide you with feedback. You’re never alone in the open source ecosystem. Understanding what it takes to manage the technical and social aspects of open source projects can help you be more successful. Learning the tools and tricks whether from resources or other maintainers can decrease the barrier to entry, help you to create a stable project, and help you to create momentum.

By cultivating your own community and having a growth mindset when it comes to your project will help you to avoid loneliness that can come with maintaining a project. It will also help you to have a good understanding of how to support your potentially growing community. You’ll learn how to establish clear paths of communication and to create a welcoming environment. You’ll learn how to interact with and support external contributors. You’ll learn how to cultivate a community that maintains high standards of code quality and documentation. What I’m trying to say is, you’ll learn a lot through this experience. You might even find your project growing. And when that happens, you’ll learn new things too.

You’ll learn how to identify potential contributors and team members who can help to drive your project forward within the goals and community needs you've set. You’ll understand how to identify potential contributors who bring value to the project, mentor them as collaborations, and you may even find that they become maintainers themselves.

The Power of Positivity (and Maybe a Cat Video Break)​

Maintaining a project can also require a healthy dose of optimism and resilience. There will be days that test your patience, but remember, with each roadblock you overcome, you're making the project stronger and more reliable. And hey, when things get tough, don't underestimate the power of a well-timed cat video break.

Becoming a Thought Leader: Share Your Wisdom​

As you gain experience and insight into open source maintenance, share your knowledge with others. Write blog posts, create tutorials, or answer questions on forums. Not only will you be helping others, but you'll also be solidifying your own understanding and enhancing your credibility in open source.

Becoming a maintainer is a challenging but incredibly rewarding journey. Embrace the learning, connect with other maintainers, and remember, a positive attitude (and maybe a cat video stash) can go a long way.

Ready to Level Up Your Maintainer Skills?​

Are you interested in starting your open source project but want more support? We've got you covered! Check out our comprehensive Becoming a Maintainer Course, packed with expert tips, tricks, and best practices to support you on your journey. Plus, once you've completed the course, head over to the maintainer guestbook and add your project so we can amplify the hard work you’ve done and connect you to more of the open source community!

This week, I'm choosing another two maintainers from the X Spaces I've been doing for OpenSauced. Thank you, Amy Dutton and Nate Wienert for being guests and supporting the open source community.

Amy Dutton​

Amy is a multi-talented Lead Maintainer on the RedwoodJS Core Team. She's kind, knowledgeable, and well-spoken, and a fantastic leader in the community. During our conversation, Amy shared the new RedwoodJS Release that includes React Server Components. She gave her insights on the importance of good developer experience and getting feedback from your users. She also talked about creating demos and projects as part of her work as a way to showcase what you can do with RedwoodJS.

• You can still listen to the space here.
• You can learn more about Redwood, here.

Nate Wienert​

Nate is the creative force behind Tamagui, a fun and innovative UI kit. He combines his technical skills with a playful approach to design, making Tamagui a delightful experience for users and developers alike. In our chat, Nate discussed the challenges and joys of building and maintaining Tamagui, including finding sponsors for his project. He shared the importance of building something useful, being consistent, and the sharing the interesting things you learn along the way.

• You can still listen to the space here.
• You can learn more about Tamagui here
• You can check out the site for Tamagui here.

Thank you Amy and Nate for your support of the open source community!

Let us know who your favorite maintainers are so we can feature them this month!

We have some big events coming up next week with OpenSauced, including a Product Hunt Launch for StarSearch. Stay tuned for an exciting Maintainer month!

It is very important to take the time to fill out these forms and templates completely and accurately. This not only makes the process smoother and faster for everyone involved but also ensures that your contribution is given the attention and consideration it deserves, benefiting both you as a contributor and us as maintainers.

So, in this blog post, I will explain why completing them is crucial and how you can do it effectively.

What are Issue Forms and PR Templates, and Why are They Important?​

Issue forms and PR templates are structured questions or guidelines you encounter when creating a new issue or PR in a repository. They serve as a roadmap, guiding you through filling in information and ensuring all details reviewers need are provided.

These forms and templates are essential for several reasons:

1. Clear Communication: They ensure you provide all the necessary information for reviewers to understand your changes. This reduces back-and-forth communication and prevents misunderstandings.
2. Efficient Review Process: By providing structured information, maintainers can more easily review the contribution and provide feedback. This speeds up the review process, benefiting both contributors and the project.
3. Consistency: Using the same forms and templates for all contributions creates consistency across issues and PRs. This makes searching, sorting, and managing contributions easier, ensuring no missing information.

Filling In the Forms and Templates​

When filling in these forms and templates, you should keep these in mind:

• Follow the Instructions: Read them carefully, pay attention to the instructions, and fill in all sections that don't say "optional" or "for the staff or core members to fill." If there are specific instructions, make sure to follow them.

• Be as Detailed as Possible: Provide a short and clear title and detailed description of your changes or proposal. Include specific examples and steps to reproduce issues or explain the reasons behind your PR.

• Don't Delete Anything: Even if you think a section doesn't apply to your contribution, don't delete it. Instead, leave a comment explaining why it's not relevant or provide a brief "N/A" response. If you're unsure what to fill in, you can look at previous issues and PRs. See how other contributors have done that.

Filling In Issue Forms​

Various issue forms can be provided in a project for different purposes, such as bug reports and feature requests. Issue forms are easier to navigate and fill out. Instructions in these forms are usually written right below the input label, as shown in the red boxes below, or as a placeholder.

Fill in all input with as detailed information as possible. If you, for example, request a new feature, convince the maintainers why they want to add this feature to the project in the description. If you're reporting a bug, describe the bug in detail, such as what you encountered, the expected behavior, and steps to reproduce the bug. Provide visual aids such as screenshots or screen recordings if the bug is a UI-related problem.

Filling In PR Templates​

PR templates are trickier than issues because they are shown and must be filled out in Markdown.

But I have some tips that I hope can help you when filling in PR templates:

• Preview mode: Click the "Preview" tab to see the sections you must fill in before you do so. It will be easier for you to notice them in this mode, but note that you cannot edit in the preview mode.
• Headings: Now that you're back in writing mode, pay attention to the headings with # symbols. You need to provide information right under these headings. Don't skip any heading.
• Comments: The instructions on what information you must provide are usually written in the comments under each heading. Read and follow all instructions thoroughly.

Here is an example of a PR template in Markdown at OpenSauced:

## Description

<!--
Please do not leave this blank
This PR [adds/removes/fixes/replaces] the [feature/bug/etc].
-->

## Related Tickets & Documents

<!--
Please use this format link issue numbers: Fixes #123
https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword
-->

## Mobile & Desktop Screenshots/Recordings

<!-- Visual changes require screenshots -->

## Steps to QA

<!--
Please provide some steps for the reviewer to test your change. If you have wrote tests, you can mention that here instead.

1. Click a link
2. Do this thing
3. Validate you see the thing working
-->

## Tier (staff will fill in)

- [ ] Tier 1
- [ ] Tier 2
- [ ] Tier 3
- [ ] Tier 4

## [optional] What gif best describes this PR or how it makes you feel?

<!-- note: PRs with deleted sections will be marked invalid -->

<!--
  For Work In Progress Pull Requests, please use the Draft PR feature,
  see https://github.blog/2019-02-14-introducing-draft-pull-requests/ for further details.

  For a timely review/response, please avoid force-pushing additional
  commits if your PR already received reviews or comments.

  Before submitting a Pull Request, please ensure you've done the following:
  - 📖 Read the Open Sauced Contributing Guide: https://github.com/open-sauced/.github/blob/main/CONTRIBUTING.md.
  - 📖 Read the Open Sauced Code of Conduct: https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md.
  - 👷‍♀️ Create small PRs. In most cases, this will be possible.
  - ✅ Provide tests for your changes.
  - 📝 Use descriptive commit messages.
  - 📗 Update any related documentation and include any relevant screenshots.
-->

Here is a mini challenge for you. After looking at the PR template above, try to answer the questions below. You can also share your answers in the comments.

1. How many sections are there in the template that you must fill in?
2. What is the format to link a related issue?
3. An important note is included in this template. If you don't follow it, your PR might not be accepted. What does this note say?

Now, let's continue where we left off. When filling in the PR template, you must ensure you provide the following:

• Short and clear title. Your title needs to describe the change that you make. For example, "fix: broken link to the About page".

• Detailed description. Explain your changes in as much detail as possible. What did you fix? How did you fix it? Did you add a new function or modify a function? Consider using bullet points if there are several changes and link the resources you use to back up your changes. Here is an example:
  

  ## Description
  
  This PR fixes the long repos' names that are partially stacked at the back of another name in the search input of the Explore tab.
  
  The changes made here:
  
  - Add Tailwind className:
  
    - [`truncate`](https://tailwindcss.com/docs/text-overflow#truncate) to truncate overflowing text.
    - [`tracking-tighter`](https://tailwindcss.com/docs/letter-spacing) to reduce letter spacing for better space.
    - `inline-block` to the `<span>` .
  
  - Remove Tailwind classNames:
    - `overflow-hidden` as it's [included in the `truncate`](https://tailwindcss.com/docs/text-overflow).
    - `break-all` as we don't want to add line breaks.
  

• Related issue(s): Most open source projects don't receive unsolicited PRs (PRs that are not accompanied by an issue). One reason is to avoid spam PRs that might introduce irrelevant, low-quality, or harmful changes to the project's codebase.

  So, when you create a PR, you want to include the number of the related issue. Add a keyword of "Closes", "Fixes", or "Resolves" in front of the issue number, like "Closes #123". Linking a pull request to an issue will automatically close the issue once the PR gets merged. You can find the issue number right after the issue's title.

  

• Screenshots or screen recordings: If your changes relate to UI improvement, consider adding screenshots or screen recordings to show the before-and-after changes.

Conclusion​

Taking the time to fill out issue forms and PR templates thoroughly demonstrates respect for the project and its maintainers. It also ensures that your contributions are well-received, efficiently reviewed, and more likely to be merged. Remember, every project is unique, so always refer to the guidelines and templates the maintainers provide.

If you don't know, May is Maintainer Month. You can show your love and appreciation to open source maintainers in many ways, including completing those forms.

This week, I'm choosing two maintainers from the X Spaces I've been doing for OpenSauced. I really learn a lot from my conversations with maintainers, but in both of these conversations I've returned to the wisdom they shared over and over again. Thank you, @danielroe and @bholmesdev for being guests and supporting the open source community.

Daniel Roe​

Daniel brings his experience as a maintainer to Nuxt.js as leader of the core team. When we chatted, I really appreciated his focus on equipping other people to be able to grow and to support the project in different ways. Another part of the conversation that stood out to me was his desire to empower contributors. As part of that, he even offers time for contributors to book a call with him!

• You can still listen to the space here.
• You can learn more about Nuxt, here

Ben Holmes​

Ben talked about being a Core maintainer for Astro and how he found that role. He shared a lot about how he sees the community and the importance of leaving a positive impact on the open source ecosystem. He shared his experience of shipping your personal open source projects without waiting for perfection.

• You can still listen to the space here
• You can learn more about Astro here

Let us know who your favorite maintainers are so we can feature them this month!

Sneak Peek - Watching:​

We're about to launch a new feature called StarSearch - your copilot for git history - and you can see what it said about Daniel Roe in the teaser below or view the full gif here, and if you're interesting in beta testing, you can sign up for the waiting list and share with your friends.

StarSearch is our AI-powered feature that provides in-depth insights into contributor history and activities, bringing transparency and a new depth of knowledge about open source projects.

What Can You Discover with StarSearch?​

• Contributor Activities: Learn the details of contributions and contributors.
• Key Contributors: Identify the key contributors to projects and ecosystems.
• Work-Based Connections: Find potential collaborators based on their contributions to specific projects
• Hidden Experts: Discover untapped talent in the ecosystem.

A Solution to Sourcing Talent​

Recently, Adam Wathan of Tailwind CSS expressed a challenge: attracting applicants well-versed in a niche combination (Rust and Tailwind) despite offering competitive salaries.

Inspired by this challenge, we asked ourselves, "Wouldn't it be cool if we built something to find this persona?" StarSearch allows you to get answers to your questions even when you don't have the context. The context for this question: most of the developers on the list work on front-end focused teams with an interest in developer performance. We’re not just another tool; we're here to redefine the meaning of open source.

Let's uncover the stories behind the code together - Join the Waitlist Today and share with your friends.

But what if there was a way to tear down those walls and build bridges of understanding instead? That's where the documentation comes in.

In this post, we will explore why clear and comprehensive documentation is the key to a thriving open source community.

What Exactly is Documentation (Docs)?​

Open source documentation, often shortened to "docs", is essentially written guides that explain everything you need to know about an open-source project. Think of it as a friendly guide that welcomes newcomers and empowers experienced users. It explains how things work, how to get started, and how to contribute to a project.

And good documentation is like a bridge connecting the code and the people who will use it.

The Three Pillars of Open Source Documentation​

Open source projects have three main types of documentation, each serving a specific purpose:

1. Technical Documentation​

This is the developers' documentation. It delves into the codebase, explains APIs, and provides instructions for setting up development environments. README and API documentation are examples of technical documentation.

2. Product Documentation​

This type of documentation is meant for general users. Think user manuals that guide them through using the project and its features, such as installation guides, tutorials, troubleshooting guides, and FAQs.

3. Guidelines​

These are the rules and roadmap for new contributors. Common types of guidelines in an open source project are:

• Contribution Guidelines: They usually explain how to submit code and bug reports and how to participate in the project, such as the contribution process and communication etiquette.
• Style Guides: They mainly guide contributors in maintaining coding and documentation consistency and quality.

Why Does Documentation Matter? Let's Break it Down!​

So, why exactly is good documentation so crucial? It benefits everyone involved in the open source ecosystem:

For Users​

Clear documentation empowers users to quickly grasp the project's functionality and unlock its full potential. It reduces frustration by providing solutions to common problems and guiding users through advanced configurations that they can do independently and efficiently. Overall, it can improve user experience and increase the possibility of your software to attract and gain new users.

For Contributors​

Clear documentation attracts new contributors by streamlining collaboration. Everyone can understand the expectations and contribute effectively. With detailed instructions, code reviews become faster, and PRs merge quickly. And that can make contributors happy! Happy contributors are most likely coming back for more contributions. The more contributors a project has, the faster it grows and innovates.

For Maintainers​

Comprehensive documentation makes maintaining the project much smoother. It reduces the number of repetitive questions from users and allows maintainers to focus on improving the project.

Good documentation attracts new users and contributors who are excited to explore a project with a welcoming guide, which leads to a sustainable project that thrives in a vibrant community.

Keys to Clear and Accessible Documentation: Reaching a Global Audience​

Open source projects are inherently open and global, attracting users and contributors from all corners of the world. To ensure everyone benefits from your documentation, consider these tips:

• Simple and Clear Language: Avoid overly technical jargon and complex sentence structures. You also want to break down complex concepts into bite-sized pieces. Write it like you're explaining things to a friend who's not a developer. Think of people with different language and cultural backgrounds. They should be able to understand the documentation as well.

• Structure and Organization: Your documentation needs to be structured logically for better flow and understanding. Remember to make it easy to navigate, for example, by providing a clear table of contents.

• Visual Aids: When possible, complement text with screenshots, screen recordings, diagrams, and code examples. Visuals can break down complex concepts and make the documentation more engaging for all readers.

• Consistency: A clear and consistent formatting and style throughout the documentation creates a professional and easy-to-navigate experience.

• Multiple Languages: If possible, consider translating your documentation into various languages. This opens the door for a broader audience to contribute and benefit from the project.

• Active Maintenance: Treat your documentation as a living document. Encourage user feedback and keep it up-to-date with the latest project developments.

The Call to Action: Be a Documentation Champion​

Whether you're a seasoned developer or just starting your open source journey, you can contribute to making documentation in open source projects accessible and welcoming. Here's what you can do:

Contribute to Existing Projects​

Many open source projects rely on community members to improve their documentation. Let's start small by contributing to the existing docs of a project you care about.

Look for contribution opportunities, such as creating issues to report typos, missing steps in instructions, or anything else you can find. You can also search for a documentation-related issue that needs help and make a pull request. Another way is to write tutorials on their docs or as a blog post. Or, if you're proficient in other languages, you can help translate their existing content.

Start Documenting Your Projects​

If you have a project, start documenting it. You never know if you will make it open source in the future. But even if you don't, you'll have a well-documented project. Who knows, you can help others understand your project and inspire others to document theirs, too!

Advocate for Clear Documentation​

Share your knowledge and help others succeed! To support others in the community, you can create content such as blog posts and tutorial videos about a project, do live streaming, or share valuable resources—like this blog post if you find it informative.

Conclusion​

Documentation is the unsung hero that keeps open source projects and its community thriving. Clear and accessible documentation can empower users, attract contributors, and strengthen the foundation for maintainers. By investing in documentation, we build bridges of understanding, opening doors to a world of collaboration and limitless possibilities.

Remember, contributing to open source projects is not always about code. Sometimes, the most powerful tool is a well-written explanation! So, let's unlock the full potential of open source, together, one well-written document at a time!

Author note: I recently gave a lightning talk about the same topic in the Virtual Coffee community. If you prefer a video over a blog post, feel free to check it out!

Have you ever experienced the frustration of your PR being rejected or stuck in a never-ending review process? It can be demotivating and time-consuming, especially when you're eager to see your changes integrated into the project.

I want to share my perspective as a maintainer so you understand what it looks like from this side. Rejecting pull requests, especially because of things that can be prevented, has always been heartbreaking. Communicating back and forth with contributors because information is missing in PR forms or because they need to follow the existing guidelines can be frustrating. As a maintainer, I lose my time and productivity and sometimes find myself on the edge of burnout.

But here is the good news: There are secret recipes for getting your pull requests reviewed and merged faster, which also help maintainers save time and avoid burnout. I'll share them with you in this blog post.

The Magic of Issues: Ensure Your PR Has a Companion​

Here's the golden rule: Always have an issue accompanying your PR.

Before working on any changes, ensure your PR is related to an issue or create one if none exists. This step is crucial because it provides context and a clear purpose for your PR. Think of an issue as a compass that guides your PR in the right direction. It ensures that your code changes align with the project's needs and helps reviewers understand the "why" behind your work.

Proposing a Feature or Reporting a Bug​

Let's say you have a brilliant idea for a new feature or stumbled upon a bug. The first step is to create an issue. Propose your idea, describe the bug, and seek initial feedback from the project maintainers.

Wait for them to triage your issue before making any changes. They will let you know if it's a go or unnecessary for the project. It's always better to have that confirmation to avoid any potential misunderstandings or wasted effort.

Following Requirements for Existing Open Issues​

If you're working on an existing open issue, make sure you follow the requirements and instructions provided in the issue. Following and sticking to them increases the chances of your PR being accepted and streamlines the review process.

Remember, just because you have an idea for an improvement outside what is required in the issue doesn't mean it's automatically the right solution. The project maintainers have a broader perspective on the project's vision and roadmap. Discussing your ideas first shows respect for their expertise and ensures your PR is well-received.

Unlocking the Secrets: Reading the Project Documentation​

It might seem tempting to jump straight into the code, but taking the time to read the project documentation, such as the README and the contributing guidelines, will save you and the reviewers valuable time and avoid headaches in the long run.

One of the reasons I have rejected PRs is that the contributor didn't follow the contributing guidelines or the instructions to run the project, which caused the project rendering or building not to work correctly.

Project documentation is like a treasure map, guiding you through the project's structure, design decisions, and contribution guidelines. It holds the secrets to understanding the project itself and the do's and don'ts of contributing.

Every project is unique, and contributing to open source requires understanding and respecting the project's specific guidelines. Some projects might have strict coding style guidelines, while others may have particular requirements for commit messages or PR descriptions.

So, before you start coding, invest some time in reading the docs. It's an investment that will pay off in the form of smoother PR reviews and a deeper understanding of the project as a whole.

Branching Out: Creating a New Branch for Changes​

Always create a new branch before making any changes. This may seem like an obvious step, but it's worth emphasizing. Working directly on the default branch (usually the main branch) can lead to chaos and version control nightmares, especially in larger projects with multiple contributors.

Imagine working on a painting. You wouldn't want to experiment with new colors directly on the finished piece, would you? Creating a new branch ensures that your changes are isolated from the main codebase until they are ready for merging. It allows you to experiment, make mistakes, and refine your code without affecting others.

When creating your branch, give it a descriptive name that reflects your changes. For example, "fix-login-bug" or "feat/add-submit-button" clearly communicate the scope of your work.

You must know that PRs with changes made directly on the default branch often get rejected. So, always create a new branch as a safe space to work on your changes. It's a simple yet crucial step towards a smoother PR process.

A Peek into the Past: Learning from Merged and Closed PRs​

Take some time to browse through previously merged and closed PRs.

Study the merged PRs. See how other contributors have structured their pull requests, the level of detail they provide, and how they respond to feedback. This can be a great way to understand what reviewers look for and ensure your PR is clear and detailed.

Even more importantly, analyze closed PRs. Look for common reasons for rejection, such as missing information, incomplete tests, code that doesn't align with the project's style or vision, etc. By doing so, you can avoid making the same mistakes in your PR.

Fill in the Blanks: Complete the PR Form with Detail​

Many projects have a PR template. Don't treat these as "just" formalities; don't remove any part of the template just because you think it is unnecessary or would make your PR look clean.

The PR template guides you in giving all the information the maintainers need to review your PR. You must fill it out thoroughly, clearly describing your changes and the problem you're solving.

Typically, here is what to include:

• Descriptive Title

  Keep it short, informative, and directly related to your changes. For example, "Fix: Broken links on the navbar".

• Detailed Description

  Walk reviewers through your code, highlighting your changes' "what" and "why." Be generous with examples and explanations. Think of it as a user guide for your changes. If your PR contains several changes, as in this example, consider using bullet points or checklists. Bottom line: The PR description should give reviewers an immediate understanding of your changes.

• Testing Steps

  Provide clear instructions on how to test your changes. This helps reviewers verify that your contribution works as intended.

• Visual Aids

  Screenshots or screen recordings can be beneficial in illustrating your changes, especially for user interface modifications. Include before-and-after screenshots or a short demo video showcasing the impact of your work.

• Link to an Issue

  Include a reference to the issue your PR addresses, such as "Fixes #123" or "Closes #456". This will help the reviewer know that there is an issue related to your PR. Linking your PR to the related issue will also automatically close the issue once the PR is merged.

You can write the PR form from scratch with the above details if no template is provided.

Submitting an incomplete or carelessly written PR can lead to back-and-forth communication, delays, or even rejection. Take the time to fill out the form thoroughly, addressing each section with care.

Stay Active: Keep Your Branch Up-to-Date​

The review process can take some time. While waiting for your PR to be reviewed and merged, don't forget to keep your branch up-to-date with the main branch.

Periodically update your branch by pulling in the latest changes from the main branch. This way, you can quickly catch any potential conflicts and resolve them before they become a roadblock to your PR's acceptance.

If you need help resolving merge conflicts, read this blog post by Bekah Hawrot Weigel.

Final Words​

Getting your pull requests reviewed and merged faster is not just about following a set of recipes; it's also about sharpening your communication skills and seizing networking opportunities.

Clear and concise communication is key to a smooth PR process. By effectively communicating your changes and addressing reviewer feedback, you demonstrate your commitment to the project and make the reviewer's job easier.

Additionally, engaging with the project maintainers and the community provides valuable networking opportunities. It shows your enthusiasm and willingness to collaborate and learn, increasing the chances of your PR being accepted and opening doors for future contributions or even job searching.

So, as you apply these secret recipes, remember that they are about more than technical proficiency. They are also about building relationships and effective communication.

Maintainers are the backbone of any open source project. They review code, merge pull requests, triage issues, and keep the project moving forward. Just like contributors, maintainers also come and go. They may have other commitments outside the project or experience burnout due to the role's demands.

When I joined a maintainers team, we all started doing what we thought best. However, without a clear standard or guidelines, it quickly became chaotic. We each had our way of doing things, and there was little consistency in handling tasks.

This lack of standardization made it confusing for new maintainers like me. I often felt unsure of the "right" way to do things and had to rely on asking my team for guidance, which wasn't always efficient. It made me wonder, "Why don't we have clear guidelines for maintainers, just like we do for contributors?" From there, these maintainer guidelines were born.

Based on this experience, I will share with you the importance of having maintainers' guidelines and how to create one in this article.

From Confusion to Clarity: Why Onboarding Guidelines Matter​

Maintainer onboarding guidelines are crucial for several reasons.

• Clear role and responsibilities: Onboarding guidelines provide a clear understanding of the role and its responsibilities. Each project is unique, and maintainers need to know what is expected of them specifically within that project.
• Standardization and Consistency: Guidelines ensure consistency in handling tasks. Without them, each maintainer may have their own way of doing things, leading to confusion and inefficiency. Standardized processes make it easier for maintainers to collaborate and ensure the project runs smoothly.
• Knowledge Transfer: Onboarding documentation serves as a valuable resource for future maintainers. It captures the collective knowledge of the existing team, ensuring a smooth transition even when members move on. This continuity is crucial for the long-term health of the project.
• Reduces Burnout: Clear onboarding processes can help prevent maintainer burnout. They prevent new maintainers from feeling overwhelmed and reduce the need for constant hand-holding from existing members, leading to a more fulfilling and sustainable experience.

Documenting the Journey: From Pain Points to Guidelines​

Every project is different, and understanding the challenges in your project will help you create tailored guidelines.

You can start by acknowledging the pain points you've experienced or witnessed within the project. Here are some examples:

• When should we close a PR?
• What method should we use to merge PRs?
• If changes in a PR are requested and the contributor has resolved them, can we dismiss the review and merge it without waiting for approval from the person who requested the changes?
• How long do we keep stale PRs open before closing them?
• What criteria do we use to reject an issue?
• May a contributor take multiple issues at the same time? If so, how many?
• How do we handle code reviews and merge conflicts?
• What are the communication protocols within the team and with contributors? Are there any preferred communication channels, response times, and expectations for tone and language?

And the list can go on.

Once you have a list of your pain points, discuss them openly with the team. Ask them questions such as what their current pain points are. What processes are working well, and what needs improvement? Brainstorm solutions collaboratively and translate them into actionable guidelines.

By asking these questions and documenting the answers, you can start drafting clear guidelines that address the specific needs of your project and maintainer team.

Beyond Onboarding: A Graceful Offboarding Process​

While onboarding is crucial, it's also important to consider the offboarding process for maintainers. This ensures that the transition is smooth and respectful for all involved when a maintainer needs to move on and leave the team.

You can consider the following when drafting your offboarding process:

• Circumstances for letting a maintainer go: Define the criteria for removing a maintainer from the team, such as prolonged inactivity, lack of engagement, or failure to meet the project's code of conduct.
• Inactivity notice: Set a timeframe for inactivity before reaching out to gently remind them of their commitment. If inactivity persists, further action can be taken.
• Retirement process: What happens when a maintainer decides to step down? You might need a procedure for revoking access and ensuring a secure handover of responsibilities.

Collaboration is Key: Building Consensus with the Team​

Once you've drafted the guidelines, it's time to seek final input from the team. Share your work, solicit feedback, and discuss potential revisions.

This collaborative approach provides valuable insights from diverse perspectives and ensures everyone feels invested in the process and is on the same page. Open discussions can further strengthen the guidelines and promote a culture of transparency within the project.

It's important to remember that these guidelines are living documents. They should evolve as the project grows and adapts to changing circumstances. You need to regularly review and update them to ensure they remain relevant and helpful.

Final Words​

Investing time crafting clear onboarding documentation for maintainers is more than just good practice; it's a strategic move that strengthens your entire project.

By creating a comprehensive onboarding process for maintainers, you are not just welcoming new team members but setting them up for success. New maintainers are welcomed with a clear roadmap, existing maintainers benefit from a standardized workflow, and the project flourishes with a knowledgeable and empowered team.

So, let's give our maintainers the same warm welcome and clear direction that we offer our contributors!

Examples​

I recently built out a couple of OG images for Open Sauced for a couple of features we've rolled out over the past couple of months, Workspaces and Repository pages. They're great features that I encourage you to check out, and I encourage you to share them on socials so our beautiful OG images pop.

For example, here's an OG image for a workspace for jsr. JSR is the new JavaScript registry from the folks from Deno.

And here's the OG image for a repository page for huggingface/transformers.

Looking at the image for the jsr workspace, there is a template for the image, but there are several dynamic portions to the image.

All the sections denoted by green outlined squares are dynamic.

This dynamic info gets pulled in for the most part from the OpenSauced API.

Other parts are pulled in from the URL, like 30 for the day range, and the description comes from the query string in the OG image URL.

React to generate an image​

So, how do we use React to generate an image?

We're using og_edge from my old co-worker Matt Kane (@ascorbic), but og_edge is a direct port of @vercel/og that works on Deno and Netlify Edge Functions which run on Deno.

Under the hood, og_edge and @vercel/og use the Satori library.

Satori: Enlightened library to convert HTML and CSS to SVG.

The API for the og_edge module is pretty straightforward. It exposes an ImageResponse constructor with the following options and that's it.

{% raw %}
new ImageResponse(
  element: ReactElement,
  options: {
    width?: number = 1200
    height?: number = 630
    emoji?: 'twemoji' | 'blobmoji' | 'noto' | 'openmoji' | 'fluent' | 'fluentFlat' = 'twemoji',
    fonts?: {
      name: string,
      data: ArrayBuffer,
      weight: number,
      style: 'normal' | 'italic'
    }[]
    debug?: boolean = false

    // Options that will be passed to the HTTP response
    status?: number = 200
    statusText?: string
    headers?: Record<string, string>
  },
)
{% endraw %}

Code snippet above care of the official og_edge API reference.

To build out these OG images, we have a background image, some icons, like a star and fork icon, and we also pull in the repository organization or user's avatar. With a bit of vanilla CSS, we can position things just right. We also pull in the Inter font as that's what we use at OpenSauced.

As far as I know, og_edge does not support Tailwind like @vercel/og does. Not a dealbreaker at all, but just something to be mindful of.

One other thing we do is set cache headers as these are dynamic images where the data changes over time. Having said that, some social networks cache OG images very aggressively.

{% raw %}
      headers: {
        // cache for 2 hours
        "cache-control": "public, s-maxage=7200",
        "content-type": "image/png",
      },
{% endraw %}

Show me the code​

Here's the pull requests for the initial work on these two OG images.

Wrapping up​

Beautiful and dynamic OG images are a must if you're looking to stand out when sharing links on socials, and og_edge and @vercel/og are great options if you also want to leverage your existing React skill set.

Now go out and build your own OG images! 🖼️

Stay saucy peeps!

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

Discover AI Engineers​

I first heard about Devin on X from the Cognition Labs announcement.

But browsing the OpenSauced API endpoints for repositories with the most new stars in the last 24 hours https://api.opensauced.pizza/v2/histogram/top/stars/new and for the top forks https://api.opensauced.pizza/v2/histogram/top/forks led me to a couple of open source AI software engineer projects with potential.

Both of these projects have consistent momentum from about the same time, Devika (March 21) and OpenDevin (March 12), which corresponds to Cognition Labs announcement. You can look at my Open Source AI Engineers Workspace below to see how quickly these open source projects have grown and found contributors. It's kind of mind blowing how quickly they've progressed.

But how do these AI Engineer projects differ and what are they all about? Let's find out.

Devin: The Change-Maker of AI Engineering​

Introduced by Cognition, "an applied AI lab focused on reasoning," Devin isn't just an AI tool. It's a fully autonomous software engineer. How does this differ from things we've seen before? Devin can plan and execute complex software projects, creating a new scenario where AI can take on engineering roles. Devin doesn't just code, it also works on bug fixes, app deployment, and even training AI models. Its performance on SWE-bench, a challenging benchmark for AI in software engineering, exemplifies its revolutionary impact, and its efficiency.

OpenDevin: The Collaborative Vision​

OpenDevin is a replication of Devin, with the goal of sharing the power with the open-source community. Through community contributions and a commitment to open standards, OpenDevin wants to refine and expand the features of AI-assisted software engineering.

Devika: The Open-Source Prodigy​

Devika is an AI Software Engineer that can understand high-level human instructions, break them down into steps, research relevant information, and write code to achieve the given objective. Devika aims to be a competitive open-source alternative to Devin by Cognition AI. Devika is an Agentic AI Software Engineer that can understand high-level human instructions, break them down into steps, research relevant information, and write code to achieve the given objective.

Inspired by Devin's pioneering work, Devika was created as an open-source project. Started by Mufeed VH from Kerala, Devika aims to democratize AI's capabilities in software engineering. Leveraging Claude 3's power, Devika offers a blend of advanced AI planning and coding in a package that's both open and community-driven. As an open source project, it isn't just about technology, it's an invitation to open source contributors to define innovation in AI.

“My intention was to simply make Devika as a help that can automate the mundane tasks for engineers, probably like an intern. You can offload a lot of work to her, but she cannot be a replacement for engineers,” Mufeed VH.

Will AI Replace Software Engineers​

Based on the developments of AI software engineers like Devin, Devika, and OpenDevin, we know that AI can indeed write code. These AIs have shown they can plan, execute complex engineering tasks, find and fix bugs, and even handle entire development projects from inception to deployment. But it's not that simple, especially if you have complex existing codebases and you want them to write secure code.

Security in coding isn't just about writing error-free code. It's about understanding the broader context, potential vulnerabilities, and the latest in security research and best practices. While AI can be trained on security best practices, human oversight is still necessary.

AI's role will continue to be an important tool that can be used across industries - not just limited to tech - to take on repetitive or time-consuming tasks, and sometimes take on complex problems efficiently. Together, we'll see faster development cycles, more efficient problem-solving, and higher-quality software.

Final Thoughts​

We're not to the point that AI can replace software engineers, but we are at the point that AI is changing the tech landscape and the future. With tech changing more quickly than ever with AI innovation, Devin, Devika, and OpenDevin bring up an interesting question: what is the relationship between humans and AI? And it brings up the question thoughtfully developed by Ethan Mollick in "On the Necessity of Sin," should we treat AI like humans? Are we moving towards a future where humans work with AI to push the boundaries of software engineering, or will it eventually supersede human roles? The answer might just depend on our vision for future and whether we adopt an open source approach of transparency, openness, and collaboration.

If you like this post and want more like this, sign up for our newsletter.

HTML Forms​

HTML Forms are cool because they have plenty of built-in features.

For example, they have native form validation and access to all the inputs in a form, and at some point, because you need to submit the form, there is a mechanism to do that as well. You can use a button, <button>submit</button> or an input of type submit, <input type="submit" />, although the latter isn't used as much these days in new sites, from what I've seen.

Here is a simple form to exhibit this.

If you fill out the form and click submit, the form will submit and add a paragraph with dark green text client-side that says, "Form submitted".

There are other things in the simple form, like form validation via the required attribute on inputs, but that's not what we're here to discuss.

What we want to touch on is that the form was able to handle the submit event because it had a submit button associated with it, which was defined in HTML within the form element.

Note: you can press enter in fields to submit a form, but again, not what we're here to discuss.

How I Broke My Form​

This brings us to a new feature that I was working on for OpenSauced for a few months, workspaces. I encourage you to create your own, but for now, let's get back to the business of forms.

Here's our beautiful workspaces settings page that I implemented.

Recently, there were styling changes, which is what you see above.

Everything looked great, and I had tested it.

Narrator: he thought he had tested it, and we shipped things to production.

Once things went live, I decided to do some smoke tests, which I usually do. I went over to the beautiful workspace settings I had worked on, made some changes in the settings, and then clicked Update Workspace button. Hmm, no toast message saying the settings were updated. I checked the browser dev tools to see if there were any JavaScript errors. Nothing related to the updates. And then it dawned on me. The submit button was outside the form, and I just broke some key functionality in the app.

Side note, but luckily thanks to Netlify's deployment rollback feature, I was able to revert to the previous production deployment within about a minute of the workspace settings page being broken 😅

How I Fixed My Form​

So how did I fix it? We needed this new styling to fix several other issues related to z-indexes and layout.

For some context, the OpenSauced application is a Next.js site, so React, but I decided to put on my old school HTML hat and remembered that form elements can be associated to a form via a form attribute. What you need to do is give the form an id attribute, and the form element that you want to associate the form to needs to have a form attribute whose value is the value of the id attribute for the form.

Here's another simple form demonstrating a simplified version of my fix.

I encourage you to remove the form attribute from the button in the above CodePen to see the issue I caused.

Here's the fix I rolled out to production.

Wrapping Up​

Learning a framework is great, and I'm a big proponent of just building something, but as you continue on in your career, it's great to start getting some fundamentals into the mix.

Also, this is a perfect example of why using semantic HTML is important! It definitely helped me get out of jam! 😅

Stay saucy peeps!

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