From a6d1bb2b1831090ef9d061bc43d200cceb0a9b24 Mon Sep 17 00:00:00 2001 From: Ayu Adiati <45172775+adiati98@users.noreply.github.com> Date: Tue, 3 Sep 2024 21:39:07 +0200 Subject: [PATCH] feat: import blog posts by AdiatiAyu (#385) * feat: add a blog post about issue management * feat: add a blog post about maintainer onboarding process * feat: add a blog post about getting pr reviewed and merged faster * feat: add a blog post about the importance of documentation * feat: add a blog post about issue forms and pr templates --- ...sue-management-for-open-source-projects.md | 82 +++++++++ ...t-needs-a-maintainer-onboarding-process.md | 81 ++++++++ ...ull-requests-reviewed-and-merged-faster.md | 122 ++++++++++++ ...f-documentation-in-open-source-projects.md | 109 +++++++++++ ...-mastering-issue-forms-and-pr-templates.md | 174 ++++++++++++++++++ 5 files changed, 568 insertions(+) create mode 100644 blog/2024/2024-03-05-collaborate-conquer-grow-mastering-the-art-of-issue-management-for-open-source-projects.md create mode 100644 blog/2024/2024-04-18-the-missing-piece-why-your-project-needs-a-maintainer-onboarding-process.md create mode 100644 blog/2024/2024-04-23-the-secret-recipe-to-getting-your-pull-requests-reviewed-and-merged-faster.md create mode 100644 blog/2024/2024-04-30-building-bridges-not-walls-the-importance-of-documentation-in-open-source-projects.md create mode 100644 blog/2024/2024-05-09-streamline-your-contributions-mastering-issue-forms-and-pr-templates.md diff --git a/blog/2024/2024-03-05-collaborate-conquer-grow-mastering-the-art-of-issue-management-for-open-source-projects.md b/blog/2024/2024-03-05-collaborate-conquer-grow-mastering-the-art-of-issue-management-for-open-source-projects.md new file mode 100644 index 00000000..d03d50cb --- /dev/null +++ b/blog/2024/2024-03-05-collaborate-conquer-grow-mastering-the-art-of-issue-management-for-open-source-projects.md @@ -0,0 +1,82 @@ +--- +title: "Collaborate, Conquer, & Grow: Mastering the Art of Issue Management for Open Source Projects" +tags: + [ + "open source", + "open source issue", + "open source issue management", + "open source maintainers", + ] +authors: AdiatiAyu +slug: issue-management-for-open-source-projects +description: An open-source maintainer needs to be able to prioritize issues wisely and decide when to delegate or handle them in-house. +--- + +Have you ever faced a dilemma as a maintainer, wondering whether to tackle an issue yourself or create an issue for the community to solve? + +Knowing when to delegate tasks and involve external contributors is crucial for empowering contributors, fostering a healthy community, and keeping your sanity intact. However, there are also tasks that only the core team may and can handle. + + + +In this article, I will walk you through prioritizing issues wisely and deciding when to delegate or best handle them in-house. + +## Prioritizing Issues: A Clear Roadmap to Success + +Before deciding to delegate or tackle an issue, you must learn how to prioritize it. With a mountain of issues, effective prioritization is crucial. How do you know what to tackle first? + +It would help if you considered these factors to prioritize issues: + +- **Severity**: Critical bugs, security vulnerabilities, and blockers must be addressed first. +- **Impact**: How many users are affected? Issues impacting a large user base deserve your quick attention. +- **Difficulty**: Can the issues be resolved quickly, or will they require significant effort? Consider prioritizing these based on the time and resources that you have. +- **Alignment with project goals**: You want to focus more on issues that contribute to the project's vision rather than nice-to-have ones. +- **Community interest**: If a feature request has high community engagement, such as active discussions, and receives enough potential support, you might want to consider prioritizing it. + +Now, you know how to prioritize issues. Next, we will dive into which issues are best to delegate and which are best for you to work on yourself. + +## Empowering Your Community: When to Delegate + +Most of the time, writing an issue is more challenging and time-consuming than working on it yourself. But if you handle everything alone, you will get burnt out quickly. + +Remember, the key to open source is the community. Delegating issues to the contributors can bring fresh perspectives, lighten your workload, and foster a sense of ownership within the community. + +Now, the question is: What kind of issues do you better delegate? + +- **Bug fixes**: Clear, reproducible bugs with minimal scope are perfect for contributors to tackle. You need to ensure that these bugs are not affecting the functionality of the current state of your project, even without being fixed immediately. These types of bugs are usually related to UI performance. +- **Documentation improvements**: Updating documentation, adding tutorials, or fixing typos and grammatical errors can be tackled by anyone with a keen eye and contributors with writing skills. +- **Small feature additions**: Well-defined, self-contained features are perfect for contributors looking to expand their portfolio. You must ensure these features align with your project's vision and scope. +- **Testing**: Do you need to test specific functionalities or add test coverage to your project? These tasks, while crucial, can often be delegated. + +To manage these issues, you can label them with `bug`, `feature`, `testing`, `help wanted`, etc., depending on the issue type. + +Always remember that contributors volunteer their time to help you maintain and enhance your project. So, when time is sensitive, consider handling them in-house rather than rushing contributors to finish the issue promptly. + +Delegating issues is one of the ways to attract new contributors to your project and build your contributor pipeline. Contributors come and go; you want more contributors to stick around and contribute more after their first pull request for the sustainability of your project. + +Delegating issues will help contributors understand your project and its codebase better, and it help you offload some of your work and build a vibrant community. + +## Maintaining the Core: Issues Best Handled In-House + +Even though delegation is important in open source, some issues need to be handled immediately and can be complex and too sensitive to be taken by external contributors. + +There are three major factors that you need to consider when deciding to handle issues in-house: + +1. **Time**: When a problem needs to be addressed and handled quickly, or you need to ship a feature within a deadline, you want to take this on yourself. It's best to refrain from putting time pressure on contributors. +2. **Complexity**: The core team has more context about a feature and has a bigger picture about the direction of the production. Consider handling this in-house when you need to work on something complex. +3. **Continued communication**: Issues that require continued and regular communication between maintainers to update the progress and make prompt decisions in the process, potentially taking place outside GitHub for efficiency, are usually best left to core members. + +"In-house" doesn't necessarily mean the tasks can only be tackled by the core team. You might have that one contributor who is a well-known community member because of their work and contributions. They regularly ship quality work, know the codebase and documentation inside out, and are familiar with your project's workflow. You know you can trust these types of contributors with the in-house tasks. However, when time is essential, you want to refrain from giving the task to them and let the core team do that instead. + +Here are some types of issues that are best handled in-house: + +- **Critical bugs**: When a bug has affected the functionality of the whole project, you can consider it critical or high priority. This kind of bug can't wait and has to be fixed immediately. +- **Architectural decisions**: Major changes to the project's core structure or direction require your deep understanding. +- **Security vulnerabilities or privacy concerns**: This type of issue is sensitive, and protecting user data is your top priority. So, you need to fix these kinds of issues yourself. +- **Complex refactoring**: Extensive code overhauls often need your experienced perspective and in-depth understanding of the codebase. It requires careful planning and analysis for efficient, maintainable, and scalable code. +- **Creating or modifying guidelines**: The rules of your project and how to contribute to it are yours to determine. Having more people outside your team to throw ideas can cause you to drift away from your original intention and direction. + +Consider labeling these types of issues with `core team work`, `critical` or `high priority` to inform that these will be handled in-house. + +## Conclusion + +Mastering issue management is a game-changer for open source maintainers, but it is also an ongoing process. Adapt your strategies as your project evolves, ask for community feedback, and don't be afraid to experiment to find the best approaches. By doing so, you can transform issue management into a powerful tool for community engagement and project success. diff --git a/blog/2024/2024-04-18-the-missing-piece-why-your-project-needs-a-maintainer-onboarding-process.md b/blog/2024/2024-04-18-the-missing-piece-why-your-project-needs-a-maintainer-onboarding-process.md new file mode 100644 index 00000000..df299f19 --- /dev/null +++ b/blog/2024/2024-04-18-the-missing-piece-why-your-project-needs-a-maintainer-onboarding-process.md @@ -0,0 +1,81 @@ +--- +title: "The Missing Piece: Why Your Project Needs a Maintainer Onboarding Process" +tags: + [ + "open source", + "open source maintainers", + "open source maintainers onboarding", + "onboarding process", + ] +authors: AdiatiAyu +slug: open-source-maintainer-onboarding-process +description: Learn about the importance of onboarding open source maintainers. +--- + +In the open source community, we often focus on contributor onboarding. We ensure a clear README, contributing guidelines, and a welcoming community to guide new contributors and help them get started. But what about maintainers? + + + +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](https://docs.opensauced.pizza/contributing/opensauced-maintainers-guide/community-maintainers-guide/) 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! diff --git a/blog/2024/2024-04-23-the-secret-recipe-to-getting-your-pull-requests-reviewed-and-merged-faster.md b/blog/2024/2024-04-23-the-secret-recipe-to-getting-your-pull-requests-reviewed-and-merged-faster.md new file mode 100644 index 00000000..128bbefc --- /dev/null +++ b/blog/2024/2024-04-23-the-secret-recipe-to-getting-your-pull-requests-reviewed-and-merged-faster.md @@ -0,0 +1,122 @@ +--- +title: "The Secret Recipe to Getting Your Pull Requests Reviewed (and Merged) Faster" +tags: + [ + "open source", + "pull request", + "open source pull request", + "open source contributors", + "open source for beginners", + ] +authors: AdiatiAyu +slug: getting-pull-requests-reviewed-and-merged-faster +description: Tips for open source contributors to get their pull requests reviewed and merged faster. +--- + +One of the most satisfying moments as an open source project contributor is having your pull request (PR) merged into the `main` branch. This contribution showcases your skills, passion, and dedication to the project. However, the road to a successful PR can sometimes be bumpy and full of pitfalls. + +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](https://github.com/open-sauced/intro/pull/138), 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](../2023/2023-07-31-keeping-your-branch-up-to-date-and-handling-merge-conflicts-while-waiting-for-pr-reviews.md) by [Bekah Hawrot Weigel](../authors/bekah-hw/). + +## 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. diff --git a/blog/2024/2024-04-30-building-bridges-not-walls-the-importance-of-documentation-in-open-source-projects.md b/blog/2024/2024-04-30-building-bridges-not-walls-the-importance-of-documentation-in-open-source-projects.md new file mode 100644 index 00000000..a5fe4638 --- /dev/null +++ b/blog/2024/2024-04-30-building-bridges-not-walls-the-importance-of-documentation-in-open-source-projects.md @@ -0,0 +1,109 @@ +--- +title: "Building Bridges, Not Walls: The Importance of Documentation in Open Source Projects" +tags: + [ + "open source", + "documentation", + "open source documentation", + "open source for beginners", + "open source contributions", + ] +authors: AdiatiAyu +slug: the-importance-of-documentation-in-open-source-projects +description: Learn about the importance of documentation in open source. +--- + +Have you ever been excited to use open source software or contribute to the codebase only to hit a brick wall of confusion because the instructions are unclear? It's frustrating, right? + +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](https://www.youtube.com/live/pzLXQYZpOPU?si=-0Ra6az6qKxBPn67&t=5368) about the same topic in the Virtual Coffee community. If you prefer a video over a blog post, feel free to check it out! diff --git a/blog/2024/2024-05-09-streamline-your-contributions-mastering-issue-forms-and-pr-templates.md b/blog/2024/2024-05-09-streamline-your-contributions-mastering-issue-forms-and-pr-templates.md new file mode 100644 index 00000000..7113ca93 --- /dev/null +++ b/blog/2024/2024-05-09-streamline-your-contributions-mastering-issue-forms-and-pr-templates.md @@ -0,0 +1,174 @@ +--- +title: "Streamline Your Contributions: Mastering Issue Forms and PR Templates" +tags: + [ + "open source", + "issue forms", + "pull request templates", + "issue", + "open source issue", + "pull request", + "open source pull request", + "open source for beginners", + "tutorial", + "open source tutorial", + ] +authors: AdiatiAyu +slug: mastering-issue-forms-and-pr-templates +description: Learn about how to fill issue forms and pull request templates. +--- + +As an open source maintainer, one of my daily tasks is reminding contributors to complete their pull request (PR) templates or asking them to provide missing information on their issues. Although the [saved replies](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies/about-saved-replies) feature on GitHub helps me a lot, it still takes me time to personalize replies based on the case. This is a challenge not only for me but also for most maintainers. + +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. + +![Issue form on GitHub](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ob4ibqvbr1w5mjigxrrc.png) + +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. + ![Preview mode GitHub issue form](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/h4ifvzf7w8gb10hii082.png) +- **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: + +```markdown +## Description + + + +## Related Tickets & Documents + + + +## Mobile & Desktop Screenshots/Recordings + + + +## Steps to QA + + + +## 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? + + + + +``` + +--- + +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](https://github.com/open-sauced/app/pull/2534):
+ + ```markdown + ## 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 `` . + + - 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](https://docs.github.com/en/issues/tracking-your-work-with-issues/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. + + ![GitHub issue number](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ech5d96dzjnlibowks3c.png) + +- **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](https://dev.to/opensauced/maintainer-month-enhancing-support-for-open-source-maintainers-36km). You can show your love and appreciation to open source maintainers in many ways, including completing those forms.