diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb8e0dd..976d309 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to OpenSauced Intro +# Contributing to OpenSauced Becoming a Maintainer Course Contributions are always welcome, no matter how large or small. Before contributing, please read the [Code of Conduct](https://docs.opensauced.pizza/contributing/code-of-conduct/) and follow the directions in this guide. @@ -36,7 +36,15 @@ You can always ask for help in the `🍕opensauced-contributors-chat` channel on cd maintainer-intro-course ``` -4. Run the project. +4. Create a new branch to work on your changes. + + ```bash + git checkout -b YOUR-BRANCH-NAME + ``` + + Replace "YOUR-BRANCH-NAME" with a descriptive name for your branch — for example, `feat/add-submit-button`. + +5. Run the project. ### Running the Project Locally @@ -136,13 +144,13 @@ Follow these steps to add a new chapter to our course: Create a new Markdown (`.md`) file in the root and name the file to reflect the chapter's content—for example, `how-to-contribute-to-open-source.md` for a chapter about how to contribute to open source. - > **NOTE**: Be sure to follow naming conventions. Notice that file names are not capitalized, and there are hyphens in place of spaces between words. + !> Be sure to follow naming conventions. Notice that file names are not capitalized, and there are hyphens in place of spaces between words. 2. **Write content**. Open the newly created Markdown file in a text editor and write the content for your chapter using the Markdown syntax. You can include headings, text, images, links, lists, and other elements to present your information effectively. - > **Note**: There should only be **one** `heading 1` in each file. + !> There should only be **one** `heading 1` in each file. 3. **Test your changes**. diff --git a/README.md b/README.md index 2108a9e..ddb548a 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ Happy learning and contributing! --- -## 🤝 Contributing to this Repository +## 🤝 Contributing to OpenSauced Becoming a Maintainer Repository We encourage you to contribute to OpenSauced! All contributors are required to abide by our [Code of Conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md). Please check out the [Contributing Guidelines](CONTRIBUTING.md) for information on how to contribute. diff --git a/additional-resources.md b/additional-resources.md index c413f6e..078538c 100644 --- a/additional-resources.md +++ b/additional-resources.md @@ -13,6 +13,7 @@ On this page, you will find additional resources to help you learn more about al - [New Maintainer Resources Series](https://dev.to/bekahhw/series/25520) - [Maintainer Toolkit Series](https://dev.to/bekahhw/series/24725) by BekahHW - [Maintainer Toolkit Series](https://dev.to/nickytonline/series/24726) by Nick Taylor +- [The Missing Piece: Why Your Project Needs a Maintainer Onboarding Process](https://dev.to/opensauced/the-missing-piece-why-your-project-needs-a-maintainer-onboarding-process-np0) - [Scaling Open Source Projects: Navigating Challenges](https://dev.to/opensauced/navigating-the-challenges-of-scaling-open-source-projects-11h2) - [Collaborate, Conquer, & Grow: Mastering the Art of Issue Management for Open Source Projects](https://dev.to/opensauced/collaborate-conquer-grow-mastering-the-art-of-issue-management-for-open-source-projects-49gi) - [The Lonely Journey of Open-Source Maintainers: A Call for Connection and Recognition](https://dev.to/opensauced/the-lonely-journey-of-open-source-maintainers-a-call-for-connection-and-recognition-2ghe) diff --git a/assets/gifs/set-up-repo.gif b/assets/gif/set-up-repo.gif similarity index 100% rename from assets/gifs/set-up-repo.gif rename to assets/gif/set-up-repo.gif diff --git a/assets/images/create-issue.png b/assets/img/create-issue.png similarity index 100% rename from assets/images/create-issue.png rename to assets/img/create-issue.png diff --git a/assets/images/feature-form.png b/assets/img/feature-form.png similarity index 100% rename from assets/images/feature-form.png rename to assets/img/feature-form.png diff --git a/building-community.md b/building-community.md index 358044c..fc1f1e1 100644 --- a/building-community.md +++ b/building-community.md @@ -2,33 +2,33 @@ Open source is more than just maintaining and improving a project. It's a dynamic environment where maintainers, contributors, and users come together to collaborate, contribute, and grow. That said, the people involved in the project are the core and heart of open source. -As more and more people engage and contribute to your projects, it becomes crucial for you to provide them with the necessary support and motivation to establish a welcoming and positive community environment. Doing so can build stronger relationships and promote a sense of belonging among your community members to keep them returning and remaining dedicated. +As more people engage and contribute to your projects, it becomes crucial for you to provide them with the necessary support and motivation to establish a welcoming and positive community environment. Doing so can build stronger relationships and promote a sense of belonging among your community members, keeping them returning and remaining dedicated. In this chapter, you will learn how to build and nurture a welcoming and supportive community in open source. ## Positive Community Culture -There are many types of people when talking about engagements in a community. Some are actively engaging, some come and go, and some are lurkers. But one thing is sure: everyone has the same interest (your project), and they bring value to your project. You always want to ensure everyone feels welcomed, included, and, most importantly, safe in your community. And one of the keys to achieving that is fostering a positive community culture. +There are many types of people when talking about engagements in a community. Some are actively engaging, some come and go, and some are lurkers. But one thing is sure: everyone has the same interest (your project), and they bring value to your project. You always want to ensure everyone feels welcomed, included, and, most importantly, safe in your community. One key to achieving this is fostering a positive community culture. ### Open Communication -You want to encourage open communication in the community. Open communication allows everyone to understand what's happening around the project and community and helps to build trust and increase healthy collaboration. Everyone should feel comfortable expressing their thoughts and ideas, but at the same time, they should be able to listen and respond to others in a respectful manner. You can read the chapter [How to Communicate and Collaborate Effectively](./communication-and-collaboration.md) for tips about communication and collaboration. +You want to encourage open communication in the community. Open communication allows everyone to understand what's happening around the project and community, helps build trust, and increases healthy collaboration. Everyone should feel comfortable expressing thoughts and ideas, but at the same time, they should be able to listen and respectfully respond to others. For tips about communication and collaboration, read the chapter "[How to Communicate and Collaborate Effectively](./communication-and-collaboration.md)." ### Diversity and Inclusivity Creating a safe and welcoming community environment involves prioritizing inclusion and promoting diversity. Inclusion means treating everyone with value, regardless of background, beliefs, or opinions. By fostering a culture where everyone is encouraged to be authentic while appreciating others, you can nurture a community where everyone feels respected and valued. Building a community where everyone feels they belong is the most important thing. -### Guidelines +### Code of Conduct -Every open source project should have a Code of Conduct as a clear set of guidelines for how members within the community should behave and treat each other. You can, for example, emphasize the importance of using positive and inclusive language, treating others with respect, and avoiding discrimination or harassment. Inform them of the consequences they may face if they do not follow the guidelines. A Code of Conduct helps to prevent conflicts, promotes respect, and ensures that everyone in the community feels safe and comfortable. To create one, you can read the [How to Write a Code of Conduct](./how-to-setup-your-project.md#how-to-write-a-code-of-conduct) section. +Every open source project should have a code of conduct as a clear set of guidelines for how members within the community should behave and treat each other. You can, for example, emphasize the importance of using positive and inclusive language, treating others with respect, and avoiding discrimination or harassment. Inform them of the consequences they may face if they do not follow the guidelines. A code of conduct helps to prevent conflicts, promotes respect, and ensures that everyone in the community feels safe and comfortable. You can read the "[Code of Conduct](./how-to-setup-your-project.md#code-of-conduct)" section in the "How to Setup Your Open Source Project" chapter to create one. ### Addressing Conflicts -Imagine you're seeing a member behave disrespectfully towards another member on GitHub or Discord. Or you receive an incident report from a member saying someone harassed them. Addressing conflicts is crucial to fostering a positive culture. If you don't promptly resolve them, your community will no longer feel safe and will lose their trust in you. You can read more about managing conflicts in the [Handling Difficult Situations](./communication-and-collaboration.md#handling-difficult-situations) section. +Imagine seeing a member behave disrespectfully towards another member on GitHub or Discord, or receiving an incident report from a member saying someone harassed them. Addressing conflicts is crucial to fostering a positive culture. If you don't promptly resolve them, your community will no longer feel safe and will lose trust in you. You can learn more about managing conflicts in the "[Handling Difficult Situations](./communication-and-collaboration.md#handling-difficult-situations)" section. ### Leading by Examples -Leadership is not about being in charge. It's about taking responsibility and setting an example for others to follow. You want to demonstrate positive behavior, be respectful to others, and be willing to listen and learn. Doing so will make others follow the same steps as yours. +Leadership is not about being in charge. It's about taking responsibility and setting an example for others to follow. You want to demonstrate positive behavior, be respectful to others, and be willing to listen and learn. Doing so will encourage others to follow your example. ### Recognization and Appreciation @@ -42,7 +42,7 @@ Remember that recognizing and appreciating contributions can create a ripple eff ## Creating Opportunities for Contributions -In an open source environment, people want to make meaningful contributions and be part of the community. If you want to see return contributors, you want to create the space and opportunities to encourage them to return and contribute more. In this section, we will talk about how to create opportunities for contributions. +In an open source environment, people want to make meaningful contributions and be part of the community. If you want to see return contributors, you need to create the space and opportunities to encourage them to return and contribute more. In this section, we will discuss how to create opportunities for contributions. ### Identifying Contributors Levels @@ -50,7 +50,7 @@ To create opportunities, you need first to identify contributors' entry points. #### New Contributors -They are generally new to open source or someone new to your project. This type of contributor usually still needs hand-holding and guidance. So, you want to be able to point them to resources about the flow of open source and how to use git and GitHub. Consider having clear and updated project documentation for them to refer to. +They are generally new to open source or someone new to your project. This type of contributor usually still needs hand-holding and guidance. So, you want to be able to point them to resources about the flow of open source and how to use Git and GitHub. Consider having clear and updated project documentation for them to refer to. #### Intermediate Contributors @@ -62,11 +62,11 @@ They are seasoned open source contributors who can contribute at a high level an ### Encouraging Diverse Contributions -You want to create a space that welcomes diverse contributions, regardless of contributors' coding skills, for the success of your projects. By encouraging both coding and non-coding contributions, you can ensure everyone can participate and contribute their unique skills and perspectives. But you also need to consider the amount of support you can give them if they need it. +You want to create a space that welcomes diverse contributions, regardless of contributors' coding skills, for the success of your projects. By encouraging both coding and non-coding contributions, you can ensure everyone can participate and contribute their unique skills and perspectives. However, you also need to consider the amount of support you can give them if they need it. #### Code Contributions -Consider creating issues for all levels of contributors after identifying their entry points. The `good first issues` are usually for beginners in open source and someone new to your project. When creating a `good first issue`, think of providing suggested solutions, the lines of code that cause the issue, and resources to help them work on it. For contributors who don't need extra support, you can create an issue with `beginners` or `help wanted` labels based on the complexity. +After identifying their entry points, consider creating issues for all levels of contributors. Good first issues are usually for beginners in open source and someone new to your project. When creating a `good first issue`, think of providing suggested solutions, the lines of code that cause the issue, and resources to help them work on it. For contributors who don't need extra support, you can create an issue with `beginners` or `help wanted` labels based on the complexity. #### Documentation @@ -76,7 +76,7 @@ You can create issues to improve the documentation or encourage your community t #### Community Contributions -As your community grows, engaging with each member becomes increasingly difficult. To manage your community effectively, having people who can facilitate interactions between members and provide timely responses will be helpful. +As your community grows, engaging with each member becomes increasingly challenging. To manage your community effectively, having people who can facilitate interactions between members and provide timely responses will be helpful. You can encourage community members to contribute by engaging in online forums and chat apps. They can help answer questions, share insights, and provide support. This not only helps to build a sense of community around your project but also helps to foster a culture of collaboration and mutual support. @@ -86,7 +86,7 @@ Some of your contributors may have skills that can be useful to promote your pro #### Managing Issues -Issues management involves identifying, analyzing, and prioritizing bug issues and feature requests during development. You can create a triage team and encourage your community to help you triage and prioritize the issues in your repositories. You want to provide them with a clear guide on managing issues. You can see the OpenSauced [triage guide](https://docs.opensauced.pizza/contributing/triage-guide/) as an example. +Issue management involves identifying, analyzing, and prioritizing bug issues and feature requests during development. You can create a triage team and encourage your community to help you triage and prioritize the issues in your repositories. You want to equip them with a clear guide on managing issues like what we have at OpenSauced in our [Triage Guide](https://docs.opensauced.pizza/contributing/triage-guide/). You can also read [this article](https://dev.to/opensauced/collaborate-conquer-grow-mastering-the-art-of-issue-management-for-open-source-projects-49gi) to learn more about issue management. #### Community Events and Hackathons @@ -96,7 +96,7 @@ Organizing community events and hackathons is one way to strengthen your communi ## Fostering New Talents -After you have created opportunities for people to contribute to your project, it's important to keep track of which contributors keep coming back and consistently producing quality work. These contributors are the ones who have the potential to become core members of your community, and you want to foster their growth and development within your project. +After you have created opportunities for people to contribute to your project, it's important to keep track of which contributors keep coming back and consistently producing quality work. These contributors have the potential to become core members of your community, and you want to foster their growth and development within your project. By building a core group of community members, you can ensure that your project can continue to grow and evolve even after maintainers move on to other projects. These core members can help to onboard new contributors, share knowledge and expertise, and provide continuity in the project's development. @@ -104,11 +104,11 @@ To foster the growth of these new talents, you can provide them with mentorship, ### Identify New Talents with OpenSauced -You can utilize OpenSauced's features, [Repository Insights](https://docs.opensauced.pizza/features/repo-insights/) and [Contributor Insights](https://docs.opensauced.pizza/features/contributor-insights/), to identify new talents by tracking active project contributors. +You can utilize OpenSauced [Repository Insights](https://docs.opensauced.pizza/features/repo-insights/) and [Contributor Insights](https://docs.opensauced.pizza/features/contributor-insights/) features to identify new talents by tracking active project contributors. #### 1. Using Repository Insights -You can list the projects that you maintain on a Repository Insights Page. This feature allows you to monitor your projects' activity and identify contributors who actively contribute to and impact them. +You can list the projects you maintain on a Repository Insights Page. This feature allows you to monitor your projects' activity and identify contributors who actively contribute to and impact them. You can find more information about your contributors in the "Contributors" tab. It allows you to view their activity level, the date of their last contribution, and the number of contributions. It also gives you information on their time zone and the languages they use most. Learn more about Repository Insights for maintainers and how to create one on [OpenSauced Docs](https://docs.opensauced.pizza/maintainers/maintainers-guide-to-open-sauced/#repository-insights-connecting-your-repositories). @@ -122,4 +122,4 @@ Open source is a journey of learning, growth, and opportunity. So, building and A positive community culture that encourages diverse contributions and fosters new talents can help you attract and retain top talent, stimulate innovation, and increase productivity. By creating a supportive environment where people feel valued, respected, and empowered to share their ideas, you can unlock the full potential of your contributors and achieve your goals. -However, building a positive community culture is not a one-time task; it requires continuous effort and commitment from everyone involved. You need to invest in promoting diversity and inclusion, encouraging collaboration and teamwork, and fostering a sense of belonging. Doing so can create a culture of trust and respect that enables your community and projects to thrive. In short, building and nurturing a welcoming and supportive community is not only the right thing to do but also a great strategy to help your project and your community succeed. +However, building a positive community culture is not a one-time task; it requires continuous effort and commitment from everyone involved. You must invest in promoting diversity and inclusion, encouraging collaboration and teamwork, and fostering a sense of belonging. Doing so can create a culture of trust and respect that enables your community and projects to thrive. In short, building and nurturing a welcoming and supportive community is the right thing to do and a great strategy to help your project and your community succeed. diff --git a/communication-and-collaboration.md b/communication-and-collaboration.md index e5b02af..96b44e5 100644 --- a/communication-and-collaboration.md +++ b/communication-and-collaboration.md @@ -2,11 +2,11 @@ Effective communication and collaboration with contributors are the keys to a thriving open source community. As maintainers, you want to smoothly onboard new contributors to your projects and build a welcoming community with open lines of communication between contributors and maintainers. -In this section, we will discuss how to onboard new contributors, utilize different communication channels for your open source project's community, and maintain healthy communication. +This chapter will discuss how to onboard new contributors, utilize different communication channels for your open source project's community, and maintain healthy communication. ## Project Onboarding -Onboarding new contributors to your project is important to maintaining its health and growth. And that will become possible through establishing effective communication, starting from your project's documentation. +Onboarding new contributors to your project is essential to maintaining its health and growth. And that will become possible through establishing effective communication, starting from your project's documentation. Providing clear information and directions about the project's goals, processes, and codebase is the key to helping new contributors collaborate. Effective communication allows you to attract contributors to return, learn more about your projects, and continue contributing. That way, you can create a sustainable ecosystem where knowledge is shared, responsibilities are distributed, and the project can continue to evolve and grow. @@ -32,7 +32,7 @@ Consider these when you write or update your documentation: ### Issue Labels -Labeling issues is an excellent way to categorize and communicate the status of issues in your project. It can also be a way to create contributors' paths. The [Issues and Pull Requests](/issues-and-pull-requests.md) chapter covers this topic more in-depth. +Labeling issues is an excellent way to categorize and communicate the status of issues in your project. It can also be a way to create contributors' paths. The "[How to Handle Open Issues and Pull Requests](/issues-and-pull-requests.md)" chapter covers this topic in more deeply. The `good first issue` label is perfect to be added to beginner-friendly issues. Think of contributors who are beginners in the tech stack or open source in general. It can be a good starting point for them to contribute to your project. Consider pointing to the code blocks and providing step-by-step instructions to work on the solutions for this type of issue. @@ -40,19 +40,19 @@ If an issue is complicated and has to be fixed promptly, you can add `core team ### Issues and Pull Request Templates -Having issues and pull request templates in your project makes it easier for you to triage and review them and helps contributors understand how to approach the project and what you expect them to look closer at when creating one. +Having issues and pull request templates in your project makes it easier for you to triage and review them, and they help contributors understand how to approach the project and what you expect them to look closer at when creating one. ## Regular Communication -Providing spaces outside your project for contributors to ask questions, request guidance, and give ideas is recommended. That way, they can communicate and collaborate actively with other collaborators and maintainers. +It is recommended that you provide spaces outside your project for contributors to ask questions, request guidance, and share ideas. That way, they can communicate and collaborate actively with other collaborators and maintainers. Here are some channels for you to consider to create regular communication: ### Chat Service App -It would be best to provide a chat service app to accommodate asynchronous and synchronous communication for your community. Contributors can ask questions, connect, and collaborate openly in nearly real-time with this app, and it's also a great way to support communication in different time zones. A chat service app can also benefit you as a maintainer by quickly announcing project and community updates, asking for help, holding synchronous office hours, etc. +It would be best to provide a chat service app to accommodate asynchronous and synchronous communication for your community. With this app, contributors can ask questions, connect, and collaborate openly in nearly real-time. It's also a great way to support communication in different time zones. A chat service app can also benefit you as a maintainer by quickly announcing project and community updates, asking for help, holding synchronous office hours, etc. -Tech communities widely use the apps mentioned here. But which one to choose is based on your preference and the needs of your community. +Tech communities widely use the apps mentioned below. You can choose which one to use based on your preference and your community's needs. #### Discord Community @@ -68,7 +68,7 @@ Slack primarily targets businesses and professional teams. That said, if your co ### GitHub Discussions -[Discussions](https://github.com/features/discussions) is a collaborative communication forum for the community around an open source project. It's a feature on GitHub to ask questions, share ideas, and build connections with each other around the project. +[Discussions](https://github.com/features/discussions) is a collaborative communication forum for the community around an open source project. It's a feature on GitHub that allows users to ask questions, share ideas, and build connections around the project. You can easily enable discussions in your project by following the [complete instructions](https://docs.github.com/en/discussions/quickstart#enabling-github-discussions-on-your-repository). @@ -76,9 +76,9 @@ You can easily enable discussions in your project by following the [complete ins Another place to create a communication space is a forum. A community forum is an online space where community members connect, engage, and discuss topics with each other. -One of the benefits of having a community forum is a place for members to discuss and ask specific questions about your project. Whenever someone encounters the same problem that has been fixed before, they can fix it faster by searching for the solutions on the forum. This can increase the productivity of maintainers because you don't have to answer the same questions repeatedly. A forum is also available publicly, so it's searchable on search engines and can increase the number of users and contributors. +One of the benefits of having a community forum is that it provides a place for members to discuss and ask specific questions about your project. Whenever someone encounters the same problem that has been fixed before, they can fix it faster by searching for solutions on the forum. This can increase your productivity because you don't have to answer the same questions repeatedly. A forum is also available publicly, so it's searchable on search engines and can increase the number of users and contributors. -You can create and host a forum on a website. Or, you can make it a subdomain of your website. Take the [freeCodeCamp forum](https://forum.freecodecamp.org/) as an example for inspiration. +You can make a subdomain on your website or create a website to host the forum. The [freeCodeCamp forum](https://forum.freecodecamp.org/) is an excellent example of this. ## Effective Communication @@ -86,15 +86,15 @@ Effective communication is key to project success. It plays a vital role in reso ### Engaging with Contributors -Having contributors come back and continue contributing to the project is one of the maintainers' goals. To nurture this relationship, you should have time to engage with your contributors between tasks. +One of the maintainers' goals is to have contributors return and continue contributing to the project. To nurture this relationship, you should have time to engage with your contributors between tasks. -Start by acknowledging and thanking them for the issue or pull request they created. Ask them questions if something is unclear, and don't assume. +Start by acknowledging and thanking them for the issue or pull request they created. Ask them questions if something needs to be clarified, and don't assume. One of the golden rules in an international remote environment is never to make an assumption. Asynchronous communication, more often than not, can lead to misunderstanding because writing is different from speaking. People with different cultural and language backgrounds might need help explaining their intentions or understanding specific cultural sayings. Consider using words with explicit meanings when you communicate, and keep your message clear and short so they can understand your purpose. When you deliver a few topics, using bullet points in a comment or splitting your message into several comments is recommended. Another way to engage with your contributors is through live streams. At OpenSauced, we do monthly live streams to thank our contributors for their pull requests and other support and give shoutouts as a token of our appreciation. You can also do live streams to work on issues publicly and ask your community to attend. -Maintainers are human. Sometimes, a discussion with a contributor can upset you when you're tired or having a bad day. Always remember that you want to foster a healthy communication and welcoming environment. So, it's okay to cool down and take time to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. +Maintainers are human. Sometimes, a discussion with a contributor can upset you when you're tired or having a bad day. But always remember that you want to foster a healthy communication and welcoming environment. It's okay to cool down and take time to answer them. You can take a couple of hours or even a day before you return to them to avoid a bitter tone. ### Managing Expectations @@ -106,17 +106,17 @@ Just like maintainers, most open source contributors are volunteers. They are no #### Style Guide -You might prefer contributors to add a prefix in brackets to issue and pull request titles. For example, "[Bug]: Documentation link goes to 404 Page Not Found". Or you want them to follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to their commit messages, such as `feat: add new feature for user authentication`. In another case, you might select particular Markdown rules for your project, like one underscore for italics, two asterisks for bolds, etc. +You might prefer contributors to add a prefix in brackets to issue and pull request titles. For example, "[Bug]: Documentation link goes to 404 Page Not Found." Or you want them to follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to their commit messages, such as `feat: add user authentication`. In another case, you might select particular Markdown rules for your project, like one underscore for italics, two asterisks for bolds, etc. -Every project has its own convention to keep the consistency around it. So, don't expect your contributors to know what to do when contributing to your project. Consider communicating this in a clear style guide they must follow. You can take an example from GitHub's [style guide](https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide). +Every project has its own convention to maintain consistency. So, don't expect your contributors to know what to do when contributing to your project. Consider communicating this in a clear style guide they must follow. You can take an example from GitHub's [Style Guide](https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide). #### Support What kind of support can you provide your contributors? You can think of these amongst other supports: - **Space**: Where can contributors ask questions and throw ideas? -- **Pair programming**: Some contributors, especially beginners, might need extra guidance and hand-holding. Can you give them support in pair programming when necessary? How can they ask for one? -- **Office hours**: Regular office hours is a great way to engage directly with your contributors. It allows you to listen to their ideas and challenges, what needs to be improved, communicate with them about the direction of your project, and build a better relationship with them. +- **Pair programming**: Some contributors, especially beginners, might need extra guidance and hand-holding. Can you provide this support when necessary? How can they ask for it? +- **Office hours**: Regular office hours is a great way to engage directly with your contributors. It allows you to listen to their ideas and challenges, identify areas that need to be improved, communicate with them about the direction of your project, and build a better relationship with them. When you support your contributors, you can gain their trust and motivation and create a more collaborative and productive environment. By providing them with the help they need, you can establish a culture where everyone feels respected and supported, which leads to even greater achievements. @@ -124,13 +124,15 @@ You can add a section in your README or contributing guidelines to inform about #### Timeline -Let your contributors know how long they can expect you to review a pull request or to answer their questions. Inform them if you, for example, won't be available on weekends or after working hours. You can automate this message with an action if you prefer. Read our [Maintainer Power Ups](./maintainer-powerups.md) chapter for more information about GitHub Actions. +Let your contributors know how long they can expect you to review a pull request or answer their questions. Inform them, for example, if you won't be available on weekends or after working hours. If you prefer, you can automate this message with an action. Read our "[Maintainer Power Ups](./maintainer-powerups.md)" chapter for more information about GitHub Actions. #### Boundaries -As your project grows and gains popularity, it will attract more contributors. Creating and setting clear boundaries becomes essential to prevent you from getting burned out quickly and balance your life. Here are some ways to create boundaries: +As your project grows and gains popularity, it will attract more contributors. Creating and setting clear boundaries becomes essential to prevent you from getting burned out quickly and balance your life. -- **Take a Break** +Here are some ways to create boundaries: + +- **Take a break** You need to know that it's okay to take time off, step away from your project, and take care of yourself. You can inform your contributors that you will review their pull requests after you return. Here is an example of what you can say: @@ -138,17 +140,17 @@ As your project grows and gains popularity, it will attract more contributors. C When pull requests come during your days off, after you return, you can thank and let the contributors know you will review the pull requests. Consider to say something like this: - > "Hey {username}, I just got back from my days off. Thank you for taking this on! I need time to review it and will get back to you soon. I appreciate your patience." + > "Hey {username}, I just returned from my days off. Thank you for taking this on! I need time to review it and will get back to you soon. I appreciate your patience." -- **No Private Message** +- **No private or direct message** - Another boundary you can set is for contributors not to send you private messages on chat service apps like Discord or social media. + Another boundary you can set is for contributors not to send you private or direct messages on chat service apps like Discord or social media. The culture of open source is open communication and transparency. It is best to keep all contributors in the loop by communicating anything related to the project in the open so everyone knows what's happening and what to expect. It will also give you the necessary privacy, separating your project from your personal life. ### Handling Difficult Situations -You might need to handle difficult situations or resolve conflicts around your project's community one day. There is no easy way to handle situations like this. But sooner or later, you need to prepare yourself. +One day, you might need to handle difficult situations or resolve conflicts around your project's community. There is no easy way to handle situations like this, but you need to prepare yourself sooner or later. Here are essential things to do when handling difficult situations: @@ -156,7 +158,7 @@ Here are essential things to do when handling difficult situations: Active listening plays a vital role in handling a difficult situation. You can only resolve a problem if you understand it clearly. -Active listening is a communication skill to not only hear the words of a speaker but also try to understand their intentions completely and acknowledge their feelings. +Active listening is a communication skill that involves hearing a speaker's words, trying to understand their intentions completely, and acknowledging their feelings. Here are some techniques that you can train for active listening: @@ -178,13 +180,13 @@ Here are some techniques that you can train for active listening: #### Having Empathy and Compassion -It would be best to be emphatic and compassionate when handling a problem, for example, when you face a dispute between contributors or community members. +When handling a problem, such as a dispute between contributors or community members, it is best to be emphatic and compassionate. -You must look at and listen to the problem from both sides to keep yourself non-judgemental. Then, put yourself in their shoes to see the case from their perspective to understand it better. Empathy and compassion will help you not only resolve a conflict but also create a positive environment. +You must look at and listen to the problem from both sides to be non-judgemental. Then, put yourself in their shoes to see the case from their perspective so you can better understand it. Empathy and compassion will help you resolve a conflict and create a positive environment. #### Being Tactful and Diplomatic -A critical factor in successfully addressing a problem is to approach it in a way that values and respects the feelings and perspectives of others. This not only prevents any harm to the relationship but also leads to positive outcomes when resolving conflicts. +A critical factor in successfully addressing a problem is approaching it in a way that values and respects the feelings and perspectives of others. This can prevent harm to the relationship and lead to positive outcomes when resolving conflicts. The key is to think before you speak and choose your words wisely. You want to be able to tell the truth, but at the same time, also consider others' feelings and make them feel safe. Use positive yet direct language to prevent misunderstandings; consider balancing being straightforward and sensitive, and avoid pointing fingers. @@ -203,4 +205,4 @@ You can say something like: > - It might be a good idea to take time to fully understand the issue before starting work on a PR, as this solution is different from what we asked in the issue. If you need help or clarification, don't hesitate to reach out. > - Another thing that could be helpful is running and testing the code locally before submitting a PR. This way, you'll be able to ensure that the code runs as it should. It can save you time from going back and forth on revisions. > -> I hope you find this feedback helpful. If there's anything I can do to support you, please let me know. +> I hope you find this feedback helpful. If there's anything I can do to support you, please let me know." diff --git a/community-translations.md b/community-translations.md new file mode 100644 index 0000000..01dc3ba --- /dev/null +++ b/community-translations.md @@ -0,0 +1,3 @@ +# Community Course Translations + +We are grateful for the contributions of the community in translating this course. Although the OpenSauced team does not currently maintain these projects, we want to share the forked copy of the repositories with those taking the course. Below, you will find the latest community translations. \ No newline at end of file diff --git a/getting-practical.md b/getting-practical.md index 29c6c2e..070f6c8 100644 --- a/getting-practical.md +++ b/getting-practical.md @@ -16,7 +16,7 @@ Sometimes, the hardest part is deciding what you will work on. Here are some gen - Think about a topic you're passionate about that others might be interested in. - Think about a problem you've had to solve that others can benefit from. -Don't think too hard about it now. You can always go back and update things later. For now, if you need a place to get started, let's create a repository about your favorite open source resources. +Don't think too hard about it now. You can always go back and update things later. For now, if you need a place to start, let's create a repository about your favorite open source resources. ## Creating Your Repository @@ -28,7 +28,7 @@ We will walk through the steps to set up your project in GitHub. Although it's n - Initialize the repository with a README file and add a license. - Click the "Create repository" button. -![setting up a repo](./assets/gifs/set-up-repo.gif) +![setting up a repo](./assets/gif/set-up-repo.gif) If you're using our starter idea, you could use the following: @@ -319,7 +319,7 @@ body: - In your repository, click the "Issues" tab and then the "New issue" button. - ![create issue](./assets/images/create-issue.png) + ![create issue](./assets/img/create-issue.png) - Select the type of issue you want to create. In this example, we'll select Feature Request. - Write your issue. If you're following along the example, we'll write a feature request for a new resource: @@ -334,7 +334,7 @@ body: - Once you've completed the issues, click "Submit new issue." - ![feature-form.png](./assets/images/feature-form.png) + ![feature-form.png](./assets/img/feature-form.png) ### Promoting Your Project diff --git a/how-to-setup-your-project.md b/how-to-setup-your-project.md index 857524d..4ba3834 100644 --- a/how-to-setup-your-project.md +++ b/how-to-setup-your-project.md @@ -1,23 +1,23 @@ # How to Setup Your Open Source Project -There are a lot of things to consider when setting up your open source project. In this portion of the guide, we will walk through key components that every project needs to be successful. +There are many things to consider when setting up your open source project. In this portion of the course, we will walk through the key components every project needs to succeed. ## Detailed README -A README file contains an introduction to what your open source project is all about. A good README should be clear, concise, up-to-date, and detailed. This file is located in your root directory and serves as the first impression for your contributors. +A README file contains an introduction to your open source project. A good README should be clear, concise, up-to-date, and detailed. This file is located in your root directory and serves as the first impression for your contributors. Here are some things to consider inside your README: - project title and summary -- brief instructions on how to setup the project -- images of the app and/or code examples +- brief instructions on how to set up the project +- images of the app and code examples - tech and tools used in the project - link to the contributing guidelines -- link to the Code of Conduct +- link to the code of conduct - link to the open source license -- link to community Discord, Slack group or GitHub Discussions +- link to community Discord, Slack group, or GitHub Discussions -A README file is written in a markup language called [Markdown](https://www.markdownguide.org/). This is a popular language used in open source documentation like READMEs. +A README file is written in a markup language called [Markdown](https://www.markdownguide.org/), a popular language used in open source documentation like READMEs. Here are a few examples of good READMEs: @@ -37,13 +37,13 @@ This guide should include instructions for the following: - running the project locally - setting up Docker containers, if applicable -The best way to test your guide is by setting up the project locally using your guide. You will learn quickly if anything needs to be added or clarified if you encounter issues getting your project to work. +The best way to test your guide is by setting up the project locally using your guide. If you encounter issues getting your project to work, you will discover it quickly and can update the documentation to add or clarify the missing piece. -The installation guide is best placed at the top of your project's `README.md` file, as it is the most accessible file for your contributors. +The installation guide is best placed at the top of your project's README file, as it is the most accessible file for your contributors. -Another good place would be in the CONTRIBUTING file. This file covers topics like installation setup, testing, linting, workflows, etc. You can place the installation instructions towards the top of your CONTRIBUTING file. +Another good place would be in the CONTRIBUTING file. Besides providing guidelines about contributing to your project, this file can include installation setup, testing, linting, workflows, etc. You can place the installation instructions towards the top or bottom of your CONTRIBUTING file. You can take a look at [OpenSauced Contributing Guidelines](https://docs.opensauced.pizza/contributing/introduction-to-contributing/) as an inspiration. -If your project is on the larger side, you might consider having a separate documentation site and dedicating a section for installation there. You can use documentation site generators like [docsify](https://docsify.js.org/#/), [Docusaurus](https://docusaurus.io/), or [Starlight](https://starlight.astro.build/). +If your project is on the larger side, consider having a separate documentation site and dedicating a section for installation there. You can use documentation site generators like [docsify](https://docsify.js.org/#/), [Docusaurus](https://docusaurus.io/), or [Starlight](https://starlight.astro.build/). ## Open Source Software License @@ -69,15 +69,15 @@ To better understand which license would work best for your project, please look - [How open source licenses work and how to add them to your projects](https://www.freecodecamp.org/news/how-open-source-licenses-work-and-how-to-add-them-to-your-projects-34310c3cf94/). - [tl;dr Legal](https://www.tldrlegal.com/) -For a complete list of Open Source Initiative (OSI) approved licenses, please check out their list [here](https://opensource.org/licenses/). +For a complete list of Open Source Initiative (OSI) approved licenses, please check out [their list](https://opensource.org/licenses/). -## Code Of Conduct +## Code of Conduct -A Code of Conduct is an established set of rules and behaviors that all open source participants agree to abide by. This document helps to ensure a healthy and inclusive environment for all involved with the project. +A code of conduct is an established set of rules and behaviors that all open source participants agree to abide by. This document helps to ensure a healthy and inclusive environment for all involved with the project. -This set of rules and expectations will go in inside a CODE_OF_CONDUCT file in the root directory of your project. Most Code of Conducts are broken up into three categories: pledge, standards, and enforcement. +This set of rules and expectations will go inside a CODE_OF_CONDUCT file in the root directory of your project. Codes of conduct are generally divided into three main categories: pledge, standards, and enforcement. -> Note: Most open source maintainers will not write their own Code of Conducts from scratch. Instead they will borrow or copy from other Code of Conducts and provide attribution. +?> Most open source maintainers will not write their code of conduct from scratch. Instead, they will borrow or copy from other codes of conduct and provide attribution. ### Project Pledge @@ -87,87 +87,102 @@ The opening pledge is a statement of the type of environment that the project wa ### Project Standards -The standards section explicitly lays out what is considered acceptable and non-acceptable behavior by all project participants. +The standards section explicitly outlines what is considered acceptable and non-acceptable behavior by all project participants. Here is an example from the [OpenSauced Code of Conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md): -Examples of behavior that contribute to creating a positive environment include: - -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -- The use of sexualized language or imagery and unwelcome sexual attention or advances -- Trolling, insulting/derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or electronic address, without explicit permission -- Other conduct which could reasonably be considered inappropriate in a professional setting +> Examples of behavior that contribute to creating a positive environment include: +> +> - Using welcoming and inclusive language +> - Being respectful of differing viewpoints and experiences +> - Gracefully accepting constructive criticism +> - Focusing on what is best for the community +> - Showing empathy towards other community members +> +> Examples of unacceptable behavior by participants include: +> +> - The use of sexualized language or imagery and unwelcome sexual attention or advances +> - Trolling, insulting/derogatory comments, and personal or political attacks +> - Public or private harassment +> - Publishing others' private information, such as a physical or electronic address, without explicit permission +> - Other conduct which could reasonably be considered inappropriate in a professional setting ### Project Enforcement -If any member of the project is behaving in an unacceptable way that violates your Code of Conduct, then you will want to state explicitly what will happen in that situation. +You will want to explicitly state the consequence of what will happen if any member of the project behaves in an unacceptable way that violates your code of conduct. Here is an example from the [OpenSauced Code of Conduct](https://github.com/open-sauced/.github/blob/main/CODE_OF_CONDUCT.md): -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at hello@opensauced.pizza. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. +> Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at hello@opensauced.pizza. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +> +> Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. ### Contributor Covenant -The Contributor Covenant is a Code of Conduct you can use and adapt for your open source projects. To learn more, please visit their [website](https://www.contributor-covenant.org/). +The Contributor Covenant is a code of conduct you can use and adapt for your open source projects. To learn more, please visit the [official website](https://www.contributor-covenant.org/). ## Contributing Guidelines -A CONTRIBUTING file is a guide on how contributors can help with your project. This file is usually located in the root directory of a project so everyone can easily access it. +A CONTRIBUTING file contains guidelines on how contributors can help with your project. It is usually located in the project's root directory so everyone can easily access it. Your guide should include the following sections: - project setup instructions - guidelines for creating new issues like bug reports and feature requests -- guidelines for which issues are available for contribution +- information about which issues are available for contribution - guidelines for commit conventions for pull requests - guidelines for code and style conventions - guidelines for creating pull requests -For an in-depth look into how to create a strong CONTRIBUTING file, please read through this [OpenSauced article](https://dev.to/opensauced/how-to-make-a-delicious-contributing-guide-4bp3). +For an in-depth look into creating a robust CONTRIBUTING file, please read [this article](https://dev.to/opensauced/how-to-make-a-delicious-contributing-guide-4bp3) by OpenSauced. ## Issue Templates -Issue templates are helpful because you can guide your contributors on how to provide specific and structured information when opening issues in your project. This will help you ensure you receive the desired information to triage the issue correctly. +Issue templates help guide contributors in providing the specific and structured information needed when opening project issues. Having these templates in your repository will ensure you receive the desired information to triage the issue correctly. + +You can create various issue templates, such as bug reports, feature requests, documentation updates, etc. Inside these templates, you can have required fields like steps for reproducing the bug or a details section for a feature request. You can also attach specific labels like `feature`, `needs triage`, or `bug` to inform the types of issue templates. + +### Creating Issue Templates + +There are two ways to create issue templates on GitHub. -You can create various issue templates, like bug reports, feature requests, documentation updates, etc. Inside these templates, you can have required fields like steps on reproducing the bug or a details section for a feature request. You can also attach specific labels like "Needs triage" or "Bug" to certain types of issue templates. +#### 1. Using GitHub's Template Builder -### Using GitHub's Template Builder +To create issue templates using the GitHub's template builder, you will need to: -There are two ways to create issue templates. The first way is to use GitHub's template builder. For this option, you will need to go to your project's settings, navigate to the "Features" section, and under "Issues", click on "Set up templates". Here is a [detailed guide](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-templates) from the GitHub documentation. +- go to your project's settings, +- navigate to the "Features" section, +- click on "Set up templates" under "Issues". + +You can follow the [detailed guide](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-templates) on the GitHub documentation to create one. ![Issue template GIF](./assets/gif/issues-template.gif) -### Using YAML Files +#### 2. Using YAML Files + +You can also create custom issue templates using YAML frontmatter: + +- Create a folder called `.github` in the root directory. +- Add a folder called `ISSUE_TEMPLATE` inside the `.github` folder. -You can also create custom issue forms using YAML frontmatter. You would start by creating a folder called `.github` in the root directory. Then, you will need to add a folder inside there called `ISSUE_TEMPLATE`. (**Note**: It is important that this folder is in all caps, or else it will not work on GitHub.) + !> The name of this folder should be in all caps, or else it will not work on GitHub. -Inside the `ISSUE_TEMPLATE` folder, you can create different YAML files like a `bug.yml` or `feature.yml` file. Here is an [example bug report](https://raw.githubusercontent.com/open-sauced/.github/main/.github/ISSUE_TEMPLATE/bug_report.yml) used by OpenSauced. +- Create a YAML file like a `bug.yml` or `feature.yml` file inside the `ISSUE_TEMPLATE` folder. -To learn more about issue templates, please review the [documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) on GitHub. +Here is the [bug report template](https://raw.githubusercontent.com/open-sauced/.github/main/.github/ISSUE_TEMPLATE/bug_report.yml) that we use at OpenSauced. To learn more about configuring issue templates, please visit the [official documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) on GitHub. ## Pull Request Templates -Similar to issue templates, pull request templates allow you to guide your contributors on how to provide specific and structured information when opening pull requests in your project. This template will be in a file called `PULL_REQUEST_TEMPLATE.md`, and it is usually located either in the root directory or the `.github` directory. +Like issue templates, pull request templates allow you to guide your contributors in providing specific and structured information when opening pull requests in your project. This template will be in a file called `PULL_REQUEST_TEMPLATE.md`, which is usually located either in the root directory or the `.github` directory. Here are a few things to consider inside your pull request template: -- section for contributors to detail which changes were made and why +- section for contributors to describe the details of changes that were made and why - section for the type of change made (e.g., bug fix, feature, style update, etc.) - section to link corresponding issue tickets to the pull request (e.g., closes #123 or fixes #456) -- section to place screenshots and/or screen recordings, if applicable +- section to place screenshots and screen recordings, if applicable -Here is an example of a [good pull request template](https://raw.githubusercontent.com/open-sauced/.github/main/.github/PULL_REQUEST_TEMPLATE.md) used by OpenSauced. Please read through the [GitHub documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) to learn more about creating pull request templates. +Here is an example of a [pull request template](https://raw.githubusercontent.com/open-sauced/.github/main/.github/PULL_REQUEST_TEMPLATE.md) used by OpenSauced. Please read the [GitHub documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) to learn more about creating pull request templates. ![PR template example](./assets/img/pr-template.png) diff --git a/i18n-guidelines.md b/i18n-guidelines.md index af8420c..89a48ca 100644 --- a/i18n-guidelines.md +++ b/i18n-guidelines.md @@ -1,19 +1,19 @@ # 🌐 i18n Guidelines -Welcome to our i18n Guidelines! We appreciate your interest in translating our Intro to Open Source course. +Welcome to our i18n Guidelines! We appreciate your interest in translating our Becoming a Maintainer with OpenSauced course. At the moment, we have the course in the following languages: -- English +- [English](./README.md) ## How Can I Contribute? There are two types of i18n contributions that we accept: -1. Translate our Intro to Open Source course. +1. Translate our Becoming a Maintainer with OpenSauced course. 2. Review pull requests (PRs) and translations. -### Translate the Intro to Open Source Course +### Translate the Becoming a Maintainer with OpenSauced Course We have two types of translations: @@ -23,9 +23,9 @@ Official translations start as a post on our [discussion board](https://github.c #### 2. Community Translations -We can't always support the maintenance of translations. However, we know some contributors are willing to translate, and we value these contributions. For that reason, we have a Community Translations section. +We can't always support the maintenance of translations. However, we know some contributors are willing to translate, and we value these contributions. For that reason, we have a [Community Translations](./community-translations.md) section. -If you're interested in translating our Intro to OSS course, fork this repository and add the translation to your forked repository. Then, you can add a link to your translation in the `community-translations.md` file. +If you're interested in translating our Becoming a Maintainer with OpenSauced course, fork this repository and add the translation to your forked repository. Then, you can add a link to your translation in the [`community-translations.md`](./community-translations.md) file that you can find in the root directory. We encourage you to add it to the [discussion board](https://github.com/open-sauced/maintainer-intro-course/discussions) as well. We will consider moving it to an official translation if it becomes popular and has enough support. @@ -35,7 +35,7 @@ If you are familiar with the translated language(s), you can help us review the ## Adding Translations -First, please read our [Contributing Guide](CONTRIBUTING.md) to setting up the project locally and for the technical instruction. Then, follow these steps to add the translations: +First, please read our [Contributing Guide](./CONTRIBUTING.md) to setting up the project locally and for the technical instruction. Then, follow these steps to add the translations: 1. **Identify target languages**. @@ -43,14 +43,14 @@ First, please read our [Contributing Guide](CONTRIBUTING.md) to setting up the p 2. **Create translation files**. - Inside the "translations" directory, create a new subdirectory for each language you plan to support. Use language codes (e.g., "en" for English, "fr" for French) as directory names. + Inside the "translations" directory, create a new subdirectory for each language you plan to support. Use language codes (e.g., "en" for English, "fr" for French, etc.) as directory names. ```markdown . └── translations/ - ├── en/ (English) - ├── fr/ (French) - └── es/ (Spanish) + ├── en/ + ├── fr/ + └── es/ ``` 3. **Translate content**. @@ -100,4 +100,13 @@ When it comes to reviewing a translation PR, ask yourself the following question - Are there links that could be localized and translated? (e.g., Wikipedia and MDN links) - Is the translation correctly written following the translated language's norms and practices? -When you think a PR is ready to be merged after your suggestions were addressed (if any), approve it through GitHub's "Review Changes" button or leave an "LGTM!" in the comment section and tag the `@open-sauced/docs` maintainers. (“LGTM” is an abbreviation of “Looks Good to Me” or “Let’s Get to Merging”, often used to approve pull requests.) +When you think a PR is ready to be merged after your suggestions were addressed (if any): + +1. Click the "Files changed" tab under the PR's title. +2. Click the green "Review changes" button. +3. Select "Approve." +4. Click the green "Submit review" button. + +Alternatively, you can leave an LGTM\* in the comment section and tag the `@open-sauced/docs` maintainers. + +?> \*LGTM is an abbreviation of “Looks Good to Me” or “Let’s Get to Merging”, often used to approve pull requests. diff --git a/index.html b/index.html index cf06f19..e95f448 100644 --- a/index.html +++ b/index.html @@ -57,5 +57,6 @@ src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js" type="text/javascript" > + diff --git a/intro.md b/intro.md index 30856b8..ad230bd 100644 --- a/intro.md +++ b/intro.md @@ -1,89 +1,91 @@ # Understanding the Role of an Open Source Maintainer -Being an open source maintainer can be a very gratifying and rewarding experience. But there is a lot of work that goes into maintaining an open source project. As a maintainer you will have many responsibilities including being a contributor, leader, mentor, and community manager. +Being an open source maintainer can be a very gratifying and rewarding experience. But a lot of work goes into maintaining an open source project. You will have many responsibilities as a maintainer, including being a contributor, leader, mentor, and community manager. -This course will provide you with a comprehensive overview of a maintainer's role, including insights into daily tasks, long-term responsibilities, and the overall impact of a maintainer in an open-source project. +This course will provide you with a comprehensive overview of a maintainer's role, including insights into daily tasks, long-term responsibilities, and the overall impact of a maintainer in an open source project. ## What is an Open Source Maintainer? -An open source maintainer is responsible for maintaining the health and success of a project. Maintainers help to define the project's goals, work with other contributors, help to build a community around the project and uphold the project's quality standards. +An open source maintainer is responsible for maintaining the health and success of a project. Maintainers help define the project's goals, work with other contributors, help build a community around the project, and uphold the project's quality standards. ### A Guide and Feedback Provider -Being able to work with contributors from all backgrounds is an important skill to develop as a maintainer. Some contributors will be seasoned developers that are interested in getting started with your project. While others will be new to open source and development in general. So it is important to have good communication with your contributors. +Being able to work with contributors from all backgrounds is an important skill to develop as a maintainer. Some contributors will be seasoned developers who are interested in getting started with your project, while others will be new to open source and development in general. So, it would be best to communicate well with your contributors. Working with contributors will include assisting them with any blockers they might have and providing constructive feedback so they can grow and strengthen their contributions to your project. ### A Welcoming Community Nurturer -Not all open source communities are welcoming and inclusive which can deter people from wanting to participate in open source at all. So it is important to remember to always lead with kindness, patience and understanding. +Not all open source communities are welcoming and inclusive, which can deter people from wanting to participate in open source at all. So, you must consistently lead your community with kindness, patience, and understanding. -People are volunteering their time to contribute to your project with the intention of helping it grow. By setting a standard that your community is inclusive and helpful to everyone, that will trickle down to all community members and create a community that contributors will want to be a part of. +People are volunteering their time to contribute to your project with the intention of helping it grow. Setting a standard that your community is inclusive and helpful to everyone will trickle down to all community members and create a community that contributors will want to be a part of. ### A Project Quality Assurance -It is maintainer's responsibility to review and maintain the project to the existing quality standards. When you receive a pull request, it is your responsibility to make sure that all of the tests are passing and the feature or fix is working as expected. It is also important to check and make sure that the new changes do not accidentally break something else in the project. Having a good testing suite and process will help with that. +One of the maintainer's responsibilities is to review and maintain the project to the existing quality standards. When you receive a pull request, you are responsible for ensuring that all of the tests are passing and the feature or fix is working as expected. It is also important to check and make sure that the new changes do not accidentally break something else in the project. Having a good testing suite and process will help with that. ## Maintainer Benefits -There are many benefits to being an open source maintainer including career, leadership and personal growth. +Being an open source maintainer has many benefits, including career, leadership, and personal growth. ### Personal and Professional Growth -As a maintainer, you are in a leadership position helping to guide contributors to success in your project. Leadership and mentorship skills are important to develop and will help you grow in your career. +As a maintainer, you are in a leadership position helping to guide contributors to success in contributing to your project. Leadership and mentorship skills are essential to develop and will help you grow professionally. -Being a maintainer also helps you grow your technical skills. You will be responsible for making contributions, reviewing pull requests, writing technical articles about your project and possibly giving technical talks at conferences. +Being a maintainer also helps you grow your technical skills. You will be responsible for contributing, reviewing pull requests, writing technical articles about your project, and possibly giving technical talks at conferences. ### Networking Opportunities -Building relationships in the tech industry is a great way to connect with talented technologists from around the world and advance your career. By working with other contributors you will get to learn from them and they will get to see your leadership and technical abilities. +Building relationships in the tech industry is a great way to connect with talented technologists worldwide and advance your career. By working with other contributors, you will get to learn from them, and they will get to see your leadership and technical abilities. -There have been many instances where long term open source relationships have turned into possible business ventures or future job opportunities. And if your project ends up being used by a lot of people, then you will be able to connect with a larger group of technologists. +There have been many instances where long-term open source relationships have become possible business ventures or future job opportunities. And if your project ends up being used by many people, you will be able to connect with a larger group of technologists. ## Maintainer Challenges -While there are many benefits to being an open source maintainer, it is not always an easy job to do. Here are a few challenges that maintainers face: +While there are many benefits to being an open source maintainer, it can also be challenging. Here are a few challenges that maintainers face: ### Burnout -A lot of open source maintainers have felt burned out on the sheer volume of work and responsibility that it takes to maintain the project. Some have even gone as far as to walk away from the project when the work became to much to handle. +Many open source maintainers have felt burned out by the sheer volume of work and responsibility it takes to maintain the project. Some have even gone as far as to walk away from the project when the work became too much to handle. -If you are feeling overwhelmed by the workload and getting close to burnout, it is time to get the right type of support for your project. Identify regular contributors in the community and reach out to them to see if they are interested in becoming a maintainer. This will help offload some of your responsibilities and decrease your stress around the project. +If you feel overwhelmed by the workload and getting close to burnout, it is time to get the right support for your project. Identify regular contributors in the community and reach out to them to see if they are interested in becoming a maintainer. Onboarding new team members will help offload some of your responsibilities and decrease your stress around the project. -When it comes to identifying possible new maintainers, you will want to look for contributors who have been invested in the project for a period of time and go above and beyond. Most contributors, will be casual contributors to your project which is fine. But there will be those who will regularly contribute and start to integrate more into the community. Those are the individuals you will want to reach out to for recruiting them to be a maintainer. +When identifying possible new maintainers, look for contributors who have been invested in the project for some time and go above and beyond. Most contributors will be casual contributors to your project, which is fine. But there will be those who will regularly contribute and start to integrate more into the community. You will want to reach out to those individuals to recruit them to be a maintainer. ### Dealing with Loneliness -The role of a maintainer can sometimes feel lonely and isolating. Most contributors will come and go and you are left still maintaining the project by yourself or with a small group of people. So it is important to get connected with a group of maintainers from a variety of open source projects so you can have a place to discuss your challenges and connect with others. +Maintaining an open source project can be challenging and overwhelming, and it sometimes feels lonely and isolated. Most contributors will come and go, and you are still left to maintain the project alone or with a small group of people. However, it's essential for you not to go through this journey alone. -Other maintainers will be able to relate to the challenges you face and will help you through the difficult times. They will also be able to offer suggestions on how to make your project and community better. It is important not to go through the maintainer journey alone. Reach out and connect with others in your same situation so you can grow and learn together. +Connecting with other maintainers from various open source projects is highly recommended so you can share your challenges, feelings, and experiences. Fellow maintainers can relate to the difficulties you are facing and offer suggestions on how to make your project and community better. By reaching out to others in similar situations, you can grow, learn from, and support each other. ## Key Responsibilities and Expectations -The role of the maintainer is a multifaceted one. Here are a few key responsibilities for an open source maintainer. +The role of the maintainer is a multifaceted one. This section will discuss a few key responsibilities of an open source maintainer. ### Triaging Issues -Learning how to triage issues is an important skill for any open source maintainer. This involves going through the existing list of open issues and prioritizing them in order of importance. Some open issues will be critical bug fixes, while others might be nice to have feature requests. Sometimes you might have issues opened for things that are not a right fit for the project. +Learning to triage issues is essential for any open source maintainer. This involves going through the existing list of open issues and prioritizing them in order of importance. Some open issues will be critical bug fixes, while others might be nice to have feature requests. Sometimes, you might have issues opened for things that are not a right fit for the project. ### Reviewing Pull Requests -Reviewing pull requests is an important part of a maintainer's job. It is the maintainer's responsibility to ensure that the suggested code or documentation update meets the projects standards and doesn't introduce any new issues for the project. You will also need to work with the contributor to unblock them on issues they have or help them resolve failing tests. +Reviewing pull requests is an important part of a maintainer's job. It is the maintainer's responsibility to ensure that the suggested code or documentation update meets the standards of the project and doesn't introduce any new issues for the project. You will also need to work with the contributor to unblock them on issues they have or help them resolve failing tests. ### Testing and Stability -A maintainer is responsible for making sure the application is working as expected. This will involve a combination of manual and automated testing. For manual testing, you will want to set time aside once in a while to run through new features or existing features like a normal user would. If there are any bugs or poor user experiences, then you will need to document them and create an issue. +A maintainer is responsible for making sure the application is working as expected. This will involve a combination of manual and automated testing. -For automated testing, you can setup an automated test suite that runs on ever pull request and merge into the main branch. If the test suite fails, then you can reach out to the contributor and help them debug the error. Good automated test suites can help catch bugs from going into production and breaking the application. +For manual testing, you will want to set time aside once in a while to run through new or existing features like a regular user would. If there are any bugs or poor user experiences, you must document them and create an issue. + +For automated testing, you can set up an automated test suite that runs on every pull request and merges into the main branch. If the test suite fails, you can reach out to the contributor and help them debug the error. Good automated test suites can help catch bugs from going into production and breaking the application. ### Documentation -A good open source project will have a comprehensive set of documentation so all users will know how to best run and maintain the project. In your project's README, you will want to have a basic overview of the project, along with how to get setup and how to contribute. As your project grows over time, you will want to keep your documentation up to date. +A good open source project will have a comprehensive set of documentation so all users will know how to run and maintain the project. In your project's README, you will want to have a basic overview of the project, along with how to set it up and how to contribute. As your project grows over time, you should keep your documentation up to date. -If you are maintaining a larger project, then you might consider using documentation builders like [Docusaurus](https://docusaurus.io/) or [docsify](https://docsify.js.org/#/) to host your documentation. Documentation also includes writing tutorials, building diagrams or creating in depth guides for the project. +If you are maintaining a larger project, consider using documentation builders like [Docusaurus](https://docusaurus.io/) or [docsify](https://docsify.js.org/#/) to host your documentation. Documentation also includes writing tutorials, building diagrams, or creating in-depth guides for the project. ### Community Management -A key component for any open source project is its community. Building a strong community can help accelerate the growth of your open source project. As new contributors discover and start to contribute to your project, you will want to create spaces for communication and collaboration. +A vital component of any open source project is its community. Building a strong community can help accelerate the growth of your open source project. As new contributors discover and start to contribute to your project, you will want to create spaces for communication and collaboration. -If your project is on GitHub, you can use [GitHub Discussions](https://docs.github.com/en/discussions) as a way for contributors to post questions and facilitate conversations. You can also look into creating communities on Discord or Slack. As you grow your community, you will want to create moderators that will help maintain the healthy environment you setup. To encourage engagement, you can hold office hours or other online events like Twitter spaces. +If your project is on GitHub, you can use [GitHub Discussions](https://docs.github.com/en/discussions) as a way for contributors to post questions and facilitate conversations. Consider creating communities on Discord or Slack and holding office hours or other events like X Spaces to encourage engagement. At one point, as you grow your community, you will want to recruit moderators to help maintain the healthy environment you set up. diff --git a/issues-and-pull-requests.md b/issues-and-pull-requests.md index 47bc7ad..794b09d 100644 --- a/issues-and-pull-requests.md +++ b/issues-and-pull-requests.md @@ -1,10 +1,10 @@ # How to Handle Open Issues and Pull Requests -One of the core responsibilities of an open source maintainer is going through the open issues and pull requests. In this section, we will talk about how to best handle open issues, pull requests, and security vulnerabilities. +One of the core responsibilities of an open source maintainer is triaging open issues and reviewing pull requests. In this chapter, we will talk about how to handle best open issues, pull requests, and security vulnerabilities. ## Issues Triage and Management -Issue triage involves reviewing an existing list of open issues and prioritizing them in order of importance. This next section will break down the most common types of issues and how to best triage and respond to contributors. +Issue triage involves reviewing an existing list of open issues and prioritizing them in order of importance. The following sections will break down the most common types of issues and how to best triage and respond to contributors. ### Bug Labeled Issues @@ -16,29 +16,29 @@ Then, you need to define whether the bug is considered critical, medium, or smal When an open issue contains a bug that is a major blocker and has affected the functionality of the whole application or website, you can consider it as high priority or critical. This kind of bug has to be fixed immediately. -Labeling these issues with a `critical` or `high-priority` is best so the team knows they must address them first. Consider using the types of colors for the labels. Using bright red or orange label colors is a good choice because it indicates the level of seriousness and is easier to spot in a list of issues. +Labeling these issues as `critical` or `high-priority` is best so the team knows they must address them first. Consider using labels in different colors. Bright red or orange label colors are a good choice because they indicate the level of seriousness and are easier to spot in a list of issues. For critical bug fixes, it is best to have core team members or regular contributors work on these issues to ensure that it is done well and promptly. You can use a label like `core team work` to indicate that this issue is only open for select members. #### Small to Medium Bugs -A bug that is not affecting the functionality of your application is not considered critical. You can categorize bugs as medium-level when you can fix them after deploying an upcoming release. And those you may or may not include in the development are considered small bugs. +A bug that is not affecting the functionality of your application is not considered critical. You can categorize bugs as medium-level when you can fix them after deploying an upcoming release. Those you may or may not include in the development are considered small bugs. -You can open these issues up for anyone to work on. Some of these issues might be small enough that it would be a good opportunity for a new contributor. In this situation, you should label the issue with a `good first issue` or `first timers only`. +You can open these issues up for anyone to work on. Some of these issues might be small enough that it would be a good opportunity for a new contributor. Label the issue with a `good first issue` or `first timers only` in this situation. ### Feature Labeled Issues When triaging feature requests, you want to ensure it is a good fit for your project and that you are interested in adding it. Reach out to the original poster of the issue to see if they want to work on it. If they agree, go ahead and assign that issue to them. Otherwise, add a `help wanted` or `accepting PRs` label on it. -Suppose the feature sounds like a good fit for the project but is complex in nature; consider working on it yourself or having a core team member assigned to it. Large features affecting many files and moving parts in your application should be handled by someone who is experienced with the codebase and won't create more issues. +Suppose the feature is a good fit for the project but is complex. Consider working on it yourself or having a core team member assigned. Large features affecting many files and moving parts in your application should be handled by someone experienced with the codebase and won't create more problems. Sometimes, users will ask for features already on the roadmap or being worked on by another contributor. If so, you can politely respond to let them know about the status. Here is a template that you can use for a response: -> Thank you for taking the time to open this issue. Another team member is currently working on this feature, and it will be added soon. As a result, we are going to close this issue. +> Thank you for taking the time to open this issue. Another team member is working on this feature, which will be added soon. As a result, we are going to close this issue. If a feature request does not sound like a good fit for your project, you can respond to the original poster and close the issue. Here is a template that you can use for a response: -> Thank you for your interest in our project. The feature you have proposed would not be a good fit for this project's current scope and direction. At this time, we will not be moving forward with this feature. +> Thank you for being so interested in our project. The feature you have proposed would not be a good fit for this project's current scope and direction. At this time, we will not be moving forward with this feature. ### Documentation Labeled Issues @@ -50,27 +50,27 @@ If an issue is clearly a spam or unhelpful message, you don't need to engage wit > This project is terrible! Nothing works, and your code is garbage. I can't believe anyone would use this. Fix it ASAP!!!111!!1! -There are no concrete details on the issues in that situation, and the poster is clearly combative. It is important not to engage with these types of users. You can close the issue and move on. +There are no concrete details on the issues in that situation, and the poster is clearly combative. It is important to refrain from engaging with these types of users. You can close the issue and move on. ### Insufficient Information Issues -If the user does not provide concrete details about the issue, then kindly respond by asking them for more information. If it is a bug report, ask for more details on how to reproduce the bug. If it is a feature request, ask for clarification on style or functionality changes. +If the user does not provide concrete details about the issue, kindly respond by asking them for more information. If it is a bug report, ask for more details on reproducing it. If it is a feature request, ask for clarification on style or functionality changes. Some users will quickly respond to replies, while others might take longer. If you don't hear a response within a week, you can message them again for more details. If a few weeks pass and the issue is not considered critical, go ahead and close the issue. ### Stale Issues -Issues that haven't been worked on for months are considered stale. Sometimes, you might be interested in resurrecting this issue and making it a higher-priority item. If that is the case, then go through the normal triage process and add the appropriate labels to it. +Issues that haven't been worked on for months are considered stale. Sometimes, you might be interested in resurrecting this issue and making it a higher-priority item. If that is the case, then go through the normal triage process and add the appropriate labels. -But other times, you might realize this is an issue that you prefer not to work on. If that is the case, go ahead and close it for good. Some maintainers automate this process using an action like [Close Stale Issues](https://github.com/actions/stale). +But other times, you might realize this is an issue that you prefer not to work on. If that is the case, go ahead and close it for good. Some maintainers automate this process using actions like [Close Stale Issues and PRs](https://github.com/actions/stale). ## Pull Requests Reviews -There are many things to consider when reviewing pull requests. In this next section, we will talk about how to provide good feedback and work with contributors on their pull requests. +There are many things to consider when reviewing pull requests. This next section will discuss how to provide good feedback and work with contributors on their pull requests. ### Effective Code Reviews -Code reviews should be informative, constructive, and helpful for the reviewer and author. Remember that contributors have volunteered their time to help your project. So, you want to ensure your review is generally positive and informative. It would be best if you considered using phrases like this: +Code reviews should be informative, constructive, and helpful for the reviewer and author. Remember that contributors have volunteered their time to help your project. You want to ensure your review is generally positive and informative. It would be best if you considered using phrases like this: > "Let's use more descriptive variable names for better readability. Instead of variable d here, let's go with days_until_deadline". @@ -78,11 +78,11 @@ While it is important to provide detailed reviews, you want to specify which cha > "This is a breaking change, and we should change it to be this instead." -If your suggested changes are minor suggestions/nitpicks, then make sure to indicate that in your review. That lets the author decide if they want to incorporate those changes in their pull request or not. +If your suggested changes are minor suggestions or nitpicks, make sure to indicate that in your review. That lets the author decide whether to incorporate those changes in their pull request. ### Manual Testing -If a pull request involves a small change to documentation or code, then manually testing the changes is unnecessary. But if the pull request involves significant changes to the project, it is best to test the changes yourself to ensure that everything is working properly. +If a pull request involves a small change to documentation or code, manually testing the changes is unnecessary. But if the pull request involves significant changes to the project, it is best to test the changes yourself to ensure that everything is working properly. If you have deployed previews set up through a service like [Netlify](https://docs.netlify.com/site-deploys/deploy-previews/) or [Vercel](https://vercel.com/docs/deployments/preview-deployments), that is a good first step to manually testing the changes. If you don't have previews set up, you should pull down the project locally to manually test the changes. It is essential to take your time to manually test everything because you are the last line of defense before a pull request is merged in. A new set of changes can break the application without proper testing. @@ -90,15 +90,15 @@ When the pull request has broken a part of the application, respond to the autho ### Missing Tests -Not all pull requests will need tests because they are small code changes or updates to documentation. But for larger features or refactors, tests should be added to help ensure that everything is working as expected. If the pull request author has not set up tests, reach out to them on the pull request to let them know what parts need to be tested. It would also help to outline adding tests in your documentation as an expectation. +Not all pull requests will need tests because they are small code changes or updates to documentation. However, for larger features or refactors, tests should be added to help ensure that everything is working as expected. If the pull request author has not set up tests, reach out to them on the pull request to let them know what parts need to be tested. It also helps to outline adding tests in your documentation as an expectation. ### Failing Automated Tests -Sometimes, contributors will open a pull request that fails a few of your automated tests. It is best to wait a few days after the pull request is opened to allow the contributor to address the failing tests and resolve the issue on their own. If they are not addressing the issue, reach out to them on the pull request and ask if they need help. When they do, look into why the test is failing and provide constructive feedback on how they can fix it. If the failing test is unrelated to their changes, let them know that it is safe to ignore it and that it will be fixed in another pull request. +Sometimes, contributors will open a pull request that fails a few of your automated tests. It is best to wait a few days after the pull request is opened to allow the contributor to address the failing tests and resolve the issue independently. If they are not addressing the issue, reach out to them on the pull request and ask if they need help. When they do, look into why the test is failing and provide constructive feedback on how they can fix it. If the failing test is unrelated to their changes, let them know that it is safe to ignore it and that it will be fixed in another pull request. If the author does not address the issue or respond to your initial comment, reply with suggested fixes and reiterate that you are here to help. After several weeks or months without the author's response, close the pull request and move on. -If multiple contributors are failing the same set of tests, then there is a possibility that the tests are flaky or broken and need your attention. In those situations, you want to clarify to the contributor that the failing test is not their fault and will be resolved. +If multiple contributors fail the same set of tests, the tests may be flaky or broken and need your attention. In those situations, you want to clarify to the contributor that the failing test is not their fault and will be resolved. ![Failed automated tests](./assets/img/failed-automated-tests.png) @@ -108,7 +108,7 @@ There might be times when you will get a spam pull request for your project. In Here are some examples of spam pull requests: -- whitespace changes to README file or other files +- whitespace changes to the README file or other files - random changes to files without an accompanying issue or explanation - numerous links to unrelated websites or promotes products/services - plagiarized content from other sources without permission or proper attribution @@ -120,19 +120,19 @@ Low-quality pull requests, unfortunately, take a lot of time and energy from the - unfinished pull requests that do not address the entire issue - code that does not fit within the established style guide for the project - incomplete pull request forms that do not provide sufficient information on what changes were made -- address multiple issues at once and make it difficult to review +- address multiple issues at once and make it challenging to review -If you receive a pull request that is lower in quality, reach out to the author, explaining what is missing and what changes need to be made. Most of the time, contributors might not be aware of these issues and need extra explanation and time to improve their pull requests. +If you receive a pull request that is lower in quality, reach out to the author, explaining what needs to be added and what changes need to be made. Most of the time, contributors might not be aware of these issues and need extra explanation and time to improve their pull requests. ### Stale Pull Requests Sometimes, pull requests can remain open for weeks or months at a time. They're not considered stale pull requests if they have regular updates and conversations. If there has been little to no activity for several weeks, you must contact the contributor to see if they need help or are still interested in working on it. -If you have repeatedly tried to reach out and get no response, you should close the pull request or take it over. If you are taking it over, tell them you are bringing this to the finish line because it is blocking other pull requests. +If you have repeatedly tried to reach out and get no response, you should close the pull request or take it over. If you are taking it over, tell the contributor you are bringing this to the finish line because it is blocking other pull requests. ## Issue and Pull Request Highlights with OpenSauced -The [Highlights feature](https://docs.opensauced.pizza/features/highlights/) on OpenSauced is a place for you to showcase recent achievements with the open source community. This is a place to introduce your project to potential new contributors and talk about issues that need attention from the community. +The [Highlights](https://docs.opensauced.pizza/features/highlights/) feature on OpenSauced is a place for you to showcase recent achievements with the open source community. This is a place to introduce your project to potential new contributors and talk about issues that need attention from the community. ![Highlights GIF](./assets/gif/highlight.gif) @@ -148,23 +148,23 @@ To learn more about how the Highlights feature works, please read through the [O ## Promptly Respond and Address Concerns -When you have incoming issues and pull requests, scheduling time for triage and reviews is important. Design a regular schedule that works for you so you can work with contributor issues and provide detailed pull request reviews during the week. +When you have incoming issues and pull requests, scheduling time for triage and reviews is essential. Design a regular schedule that works for you to triage contributor issues and provide detailed pull request reviews during the week. -You should not feel pressured to respond to new open issues or pull requests immediately. It is okay if they are left unread for a few days. If a contributor pushes you for a review or comment on an issue or a pull request, politely respond that you will get to it when you have time. You can also set up your own [GitHub Actions](https://dev.to/opensauced/github-actions-a-maintainers-best-friend-488n) to automate responses to new issues and pull requests, letting contributors know you will get to it when available. +You should not feel pressured to respond to new open issues or pull requests immediately. It is okay if they are left unread for a few days. If a contributor pushes you for a review or comment on an issue or a pull request, politely respond that you will get to it when you have time. You can also set up your own [GitHub Actions](https://docs.github.com/en/actions) to automate responses to new issues and pull requests, letting contributors know you will get to it when available. You can learn how to set one up in [this article](https://dev.to/opensauced/github-actions-a-maintainers-best-friend-488n). -If contributors have concerns about the project, then you will want to create a safe space to make them comfortable talking about these issues. If they have concerns about the code or security aspects, feel free to discuss it on an open issue or even privately through Discord or Slack. +If contributors have concerns about the project, you will want to create a safe space to make them comfortable talking about these issues. If they have concerns about the code or security aspects, feel free to discuss it on an open issue or even privately through Discord or Slack. ## Task Prioritization and Realistic Timelines -Sometimes, juggling all the tasks to maintain an open source project can be difficult. Set aside time each week to triage issues and look through the project backlog to prioritize work to be done. Choose wisely when to label issues and pull requests as a high priority. Realistically, there will always be issues that should be considered a top priority, while the rest can be addressed later. +Juggling all the tasks to maintain an open source project can be difficult sometimes. Set aside time each week to triage issues and look through the project backlog to prioritize work to be done. Choose when to label issues and pull requests as a high priority. Realistically, there will always be issues that should be considered a top priority, while you can address the rest later. When setting realistic timelines, add an extra few days to your work estimate. If you think a new set of features will take a couple of weeks, tack on each week. Issues come up all of the time in projects. So you want to avoid timeboxing yourself to a very strict deadline when it wasn't realistic in the first place. -When working with other volunteer contributors, allow extra time to complete the work. If they volunteer their time, they may run into other commitments which will delay their availability for you. It is important to lead with empathy and understanding and not demand that they adhere to a strict deadline like an employee would. +When working with other volunteer contributors, allow extra time to complete the work. If they volunteer their time, they may run into other commitments which will delay their availability for you. It is crucial to lead with empathy and understanding and not demand that they adhere to a strict deadline like an employee would. ## Security Vulnerabilities Handling -In case security issues arise within your project, your contributors must be aware of the optimal methods for reporting them. It would be best to have a policy for reporting security vulnerabilities stored in the `SECURITY.md` file. This file is usually added in the project's root or `.github` directory. It would also be good to link to the security file in your README file for easier community access. +In case security issues arise within your project, your contributors must be aware of the optimal methods for reporting them. It would be best to have a policy for reporting security vulnerabilities stored in the `SECURITY.md` file. This file is usually added to the project's root or `.github` directory. It would also be good to link to the security file in your README file for easier community access. A lot of maintainers will choose to go with this security policy template: @@ -176,4 +176,4 @@ A lot of maintainers will choose to go with this security policy template: ### Dependabot -Dependabot is a GitHub feature that will monitor your project's dependencies and report any possible security vulnerabilities found. You can configure dependabot to report issues or even create pull requests to update dependencies with security vulnerabilities. To learn more about this feature, please read through the [GitHub documentation](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide). +Dependabot is a GitHub feature that monitors your project's dependencies and reports any possible security vulnerabilities. You can configure Dependabot to report issues or create pull requests to update dependencies with security vulnerabilities. To learn more about this feature, please read through the [GitHub documentation](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide). diff --git a/maintainer-powerups.md b/maintainer-powerups.md index a438240..30bafff 100644 --- a/maintainer-powerups.md +++ b/maintainer-powerups.md @@ -1,14 +1,14 @@ # Maintainer Power Ups -As maintainers, we have a variety of daily tasks. We often juggle triaging new issues, reviewing pull requests, testing changes, and managing and moderating the community, such as welcoming new contributors and thanking contributors for their contributions. And most of the time, we are expected to respond to these tasks promptly. Sometimes, these never-ending tasks take too much time and are overwhelming. And we need to be efficient in what we do. +Maintainers have a variety of daily tasks. You often juggle triaging new issues, reviewing pull requests, testing changes, and managing and moderating the community, such as welcoming new contributors and thanking contributors for their contributions. Most of the time, you are expected to respond to these tasks promptly. Sometimes, these never-ending tasks take too much time and are overwhelming. It would help if you were efficient in what you do. -The good news is that some tools and features on GitHub allow us to automate tasks that help us save some time and make our work lighter. In this chapter, we will talk about these maintainer power ups from GitHub. +The good news is that some tools and features on GitHub allow you to automate tasks, which can help you save time and make your work lighter. In this chapter, we will talk about these maintainer power ups from GitHub. ## GitHub Actions Let's say your project receives more new issues and pull requests daily. You want to welcome each new contributor, thank them for their contributions, and tell them you will triage their issues and review their pull requests. You want to do more but don't have time to respond to them because you're still busy with something else. -Setting up an action to automate these tasks will save you time in responding to contributions individually. You can decide which actions you want to have in each repository. +Setting up actions to automate these tasks will save you time responding to contributions individually. You can decide which actions to include in each repository. ![Create GitHub Action](./assets/img/gh-actions.png) @@ -18,11 +18,11 @@ There are many types of actions that you can set up for your project, depending #### Linter -Most open source repositories have linters that run on each pull request. Linter is a tool for detecting potential errors and maintaining a consistent code style in a project. This action can help you keep the code quality and achieve a more readable and consistent style. [Super-Linter](https://github.com/marketplace/actions/super-linter) is one of the most used actions for linter. +Most open source repositories have linters that run on each pull request. Linter is a tool for detecting potential errors and maintaining a consistent code style in a project. [Super-Linter](https://github.com/marketplace/actions/super-linter) is one of the most used actions. This action can help you maintain code quality and achieve a more readable and consistent style. #### Deployed Previews -You want to be able to view changes, especially visual ones, without having to ship them to production. Having these previews in every pull request with [Netlify](https://docs.netlify.com/site-deploys/deploy-previews/) or [Vercel](https://vercel.com/features/previews) lets you preview changes before merging the pull request. +You want to be able to view changes, especially visual ones, without shipping them to production. Having these previews in every pull request with [Netlify](https://docs.netlify.com/site-deploys/deploy-previews/) or [Vercel](https://vercel.com/features/previews) lets you preview changes before merging the pull request. #### Issue and Pull Request Scripts @@ -30,7 +30,7 @@ Having scripts to welcome new issues and pull requests and let contributors know #### Code Scanning Tools -Code scanning is a tool that looks for security vulnerabilities, possible bugs, and errors in the code. You can use GitHub's [code scanning](https://docs.github.com/en/code-security/code-scanning) feature and configure tools like [CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql), which GitHub maintains, or third-party scanning tools such as [SonarQube](https://github.com/marketplace/actions/official-sonarqube-scan). +Code scanning is a tool for detecting security vulnerabilities, possible bugs, and errors in code. You can use GitHub's [code scanning](https://docs.github.com/en/code-security/code-scanning) feature and configure tools like [CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql), which GitHub maintains, or third-party scanning tools such as [SonarQube](https://github.com/marketplace/actions/official-sonarqube-scan). #### Testing @@ -40,9 +40,9 @@ Setting up actions to run tests is helpful to ensure your app functions and perf You can search for available GitHub Actions on the [GitHub Marketplace](https://github.com/marketplace?type=actions). But if you can't find the one you need, you can create or customize your own actions from existing GitHub Actions. -The founder of OpenSauced, Brian Douglas, created the [Take Action](https://github.com/marketplace/actions/contributor-takes-action). This action allows contributors to assign themselves to an issue by typing the `.take` command in the issue's comment so maintainers can focus on more important tasks than assigning issues. +Brian Douglas, the founder of OpenSauced, created [Take Action](https://github.com/marketplace/actions/contributor-takes-action). This action allows contributors to assign themselves to an issue by typing the `.take` command in the issue's comment, allowing maintainers to focus on more important tasks than assigning issues. -But we want contributors only to take issues that have passed our triage or are not meant to be worked on by the core team. So, we create the [Triage Action](https://github.com/open-sauced/app/blob/beta/.github/workflows/triage.yml) that will block the Take Action whenever a `needs triage` or `core team work` label exists. +However, we want contributors only able to take issues that have passed our triage or are not meant to be worked on by the core team. So, we create the [Triage Action](https://github.com/open-sauced/app/blob/beta/.github/workflows/triage.yml) that will block the Take Action whenever a `needs triage` or `core team work` label exists. You can read more about GitHub Actions and how to create one in [the official documentation](https://github.com/features/actions). @@ -59,7 +59,7 @@ Using Git, GitHub, and GitHub Actions to build a CI/CD pipeline should give you ### Continuous Delivery vs. Continuous Deployment -From the [official GitHub resources](https://resources.github.com/ci-cd/): +From the official [GitHub Resources](https://resources.github.com/ci-cd/): > In a CI/CD pipeline that uses continuous _delivery_, automation pauses when developers push to production. A human—your operations, security, or compliance team—still needs to manually sign off before final release, adding more delays. > @@ -76,28 +76,28 @@ Below are some helpful resources to help you build a CI/CD pipeline with GitHub ## GitHub CLI -[GitHub CLI](https://cli.github.com/) is an open source tool for using GitHub from your computer's command line. It allows you to: +[GitHub CLI](https://cli.github.com/) is an open source tool that enables you to use GitHub from your computer's command line. It allows you to: - forking and cloning repositories, - checking out a pull request and reviewing it locally, - creating issues and pull requests, - viewing a pull request, issue, or repository right from your terminal. -Using the GitHub CLI will save you time and boost your productivity as a maintainer because you don't need to switch between the GitHub website and your terminal. +Using the GitHub CLI will save you time and boost your productivity as a maintainer. You don't need to switch between the GitHub website and your terminal. -Head over to the [GitHub CLI repository](https://github.com/cli/cli#installation) for information on installing GitHub CLI on your machine, and read this [blog post](https://dev.to/opensauced/boost-productivity-with-the-github-cli-2mne) to get you started. +Visit the [GitHub CLI repository](https://github.com/cli/cli#installation) for information on installing GitHub CLI on your machine, and read [this blog post](https://dev.to/opensauced/boost-productivity-with-the-github-cli-2mne) to get started. ## Issues and Pull Request Templates Have you ever found yourself in a situation where you're reviewing pull requests or triaging issues, but you can't understand what's happening because contributors didn't provide sufficient information? Or, have you had to close an issue or pull request because the description, screenshot, or other crucial information was missing? -The good news is that you can address these problems by creating issue and pull request templates. These templates allow you to customize and standardize it to include necessary information. You can see them as guides for contributors to follow when writing an issue or pull request for your project. By creating templates, you can save time on triaging issues, reviewing pull requests, and ensuring you get all the information you need from your contributors. Additionally, future contributors can benefit from these templates by understanding the history of changes made, which can help them debug or understand the code involved. +The good news is that you can address these problems by creating issue and pull request templates. These templates allow you to customize and standardize it to include necessary information. You can see them as guides for contributors to follow when writing an issue or pull request for your project. Creating templates saves time on triaging issues, reviewing pull requests, and ensuring you get all the information you need from your contributors. Additionally, future contributors can benefit from these templates by understanding the history of changes made, which can help them debug or understand the code involved. You can learn more about [configuring issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) and [creating a pull request template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository) on the official GitHub documentation. ## Saved Replies -Sometimes, you repeatedly write the same reply to issues or pull requests. It's crucial to keep clear communication between maintainers and contributors. So, when you write all comments manually, your message will no longer be consistent, and they may be unclear. You can create saved replies when you frequently respond to issues and pull requests with the same comments. +Sometimes, you repeatedly write the same reply to issues or pull requests. Clear communication between maintainers and contributors is crucial. So, when you write all comments manually, your messages will no longer be consistent and may be unclear. You can create saved replies when you frequently respond to issues and pull requests with the same comments. [Saved replies](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies/about-saved-replies) allow you to create a reusable response to issues, pull requests, and discussions and use it across repositories. It will save you time responding to contributors while keeping the consistency of your message. You can always modify your replies if necessary. @@ -107,20 +107,21 @@ Read the GitHub documentation for complete instructions about how to [create sav ## Code Owners -Most of the time, contributors don't know the maintainers of a project, so they don't know who to add as reviewers. When they create a pull request, they usually leave a comment without tagging anyone, like, "Can you please review my PR?" Without being tagged, maintainers don't get notified about this new pull request and comment, causing it to be missed from the radar. Adding the CODEOWNERS file to the repository will help you to automate and tackle this issue. +Most of the time, contributors don't know the maintainers of a project, so they don't know who to reach out to review their pull requests. When they create a pull request, they usually leave a comment without tagging anyone, like, "Can you please review my PR?" Without being tagged, maintainers don't get notified about this new pull request and comment, causing it to be missed from the radar. Adding the CODEOWNERS file to the repository will help you to automate and tackle this issue. From the [official GitHub documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners): > You can use a CODEOWNERS file to define individuals or teams that are responsible for code in a repository. -This Becoming a Maintainer course repository has a [CODEOWNERS file](https://github.com/open-sauced/maintainer-intro-course/blob/main/.github/CODEOWNERS) that contains code as below: +Here is an example of a [CODEOWNERS file](https://github.com/open-sauced/docs/blob/main/.github/CODEOWNERS) in the OpenSauced docs repository that contains code as below: ```text -@open-sauced/triage -@open-sauced/docs +* @open-sauced/docs ``` -It means that the `@open-sauced/triage` and `@open-sauced/docs` teams are automatically added as reviewers whenever someone creates a pull request. +This syntax means that the `@open-sauced/docs` team will be the default owner for everything in the repository and will automatically added as reviewers whenever someone creates a pull request. + +!> If you want to match two or more code owners with the same pattern, all the code owners must be on the same line. There are some benefits to having this file in your repository: @@ -134,6 +135,4 @@ There are some benefits to having this file in your repository: - **Branch protection** - If you opt-in to "Require approval" and "Require review from Code Owners" to protect a branch, a certain number of code owners must approve any pull request before it can be merged into the protected branch. This can reduce the chance of merging pull requests that can break the production. - -You can read the official GitHub documentation for complete instructions to [create the CODEOWNERS file](https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files). + If you opt-in to "Require approval" and "Require review from Code Owners" to protect a branch, a certain number of code owners must approve any pull request before it can be merged into the protected branch. This can reduce the chance of merging pull requests that can break production. diff --git a/maintaining-code-quality.md b/maintaining-code-quality.md index 37a6712..c1e2cfb 100644 --- a/maintaining-code-quality.md +++ b/maintaining-code-quality.md @@ -1,18 +1,20 @@ # How to Maintain Code Quality and Documentation -When maintaining a project, keeping the code quality high and the documentation up to date is important. This will help contributors understand the project and make it easier for them to contribute. +Maintaining a project with high code quality and up-to-date documentation is important. This will help contributors understand the project and make it easier for them to contribute. -In this chapter, we will cover how to maintain code quality and documentation in your open source project. +This chapter will cover ways of maintaining code quality and documentation in your open source project. ## Code Reviews and High-Quality Contributions -Code reviews are essential to maintaining code quality in an open source project. You should take your time to review each pull request and ensure that the proposed changes are high quality and do not introduce any new bugs or issues. You will receive pull requests from contributors who are new to the project and might not be familiar with the codebase. It is important to be patient and provide constructive feedback to help them improve their contributions. +Code reviews are essential to maintaining code quality in an open source project. You should take the time to review each pull request and ensure that the proposed changes are high quality and do not introduce any new bugs or issues. You will receive pull requests from contributors who are new to the project and might not be familiar with the codebase. It is important to be patient and provide constructive feedback to help them improve their contributions. The following sections will cover some best practices for conducting code reviews and ensuring high-quality contributions. ### Conventional Commits -The Conventional Commits is a specification for structuring commit messages. It provides an easy way to understand the type of changes that are being made and helps maintain a clean and organized commit history. Using Conventional Commits in your project is recommended to help keep a clean and organized commit history. In your contributing guidelines, you can ask contributors to use it when making changes to the project. +[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) is a specification for structuring commit messages. It provides an easy way to understand the type of changes being made and helps maintain a clean and organized commit history. + +Using Conventional Commits in your project is highly recommended. You can encourage contributors to use it when making changes to the project by adding a guide to your contribution guidelines. [This section](https://docs.opensauced.pizza/contributing/introduction-to-contributing/#commits) in the OpenSauced contributing guidelines asks contributors to use Conventional Commits. Here are some examples of Conventional Commit messages: @@ -24,15 +26,13 @@ fix(login): resolve issue with incorrect password validation refactor(api): streamline error handling in user service ``` -You can learn more about Conventional Commits on the [official website](https://www.conventionalcommits.org/en/v1.0.0/). - ### Incomplete Pull Requests -The first thing to check for is to ensure the proposed changes are complete and do not introduce any new bugs or issues. It should be clear what the proposed changes are about and the problem it is trying to solve. +When you review a pull request, the first thing to check is that the proposed changes are complete and do not introduce new bugs or issues. It should also be clear what the proposed changes are about and what problem they are trying to solve. -The proposed changes should be linked to an existing issue, and all necessary information in the pull request template should be filled out. If the pull request still needs to be completed, reach out to the contributor and ask them to provide the missing information. +The contributor should link the proposed changes to an existing issue, and they should fill out all necessary information in the pull request template. If the pull request still needs to be completed, reach out to the contributor and ask them to provide the missing information. -Remember that you will be dealing with all levels of contributors. Some might be new to open source and not realize they are missing information. Giving constructive feedback with patience is important to help them improve their contributions. +Remember that you will be dealing with contributors at all levels. Some might be new to open source and not realize they have failed to provide the necessary information. Giving constructive feedback with patience is important to help them improve their contributions. ### Large and Unfocused Pull Requests @@ -42,38 +42,36 @@ Sometimes, you might get pull requests that are too large and unfocused. Example - Pull requests that refactor large parts of the codebase - Pull requests that add a lot of new functionality -Large pull requests will be challenging to review effectively and sometimes introduce bugs. In this situation, asking the contributor to break down the pull request into smaller, more focused pull requests is important. +Large pull requests can be challenging to review effectively and sometimes introduce bugs. In this situation, it is important to ask the contributor to break down the pull request into smaller, more focused pull requests. ### Automated Tests Setting up testing can help ensure that new contributions don't break existing functionality. Automated tests can be run on every pull request to ensure the new code passes all the tests. This will help maintain the quality of the code and make it easier for contributors to contribute. -If the new pull request is failing some of the tests, reach out to the contributor and ask them to fix the failing tests. Sometimes, the contributor might not understand why the tests are failing. In these cases, you need to work with the contributor to help them understand the problem and fix the failing tests. +If some tests in the new pull request don't pass the checks, contact the contributor and ask them to fix the failing tests. Sometimes, the contributor might need help understanding why the tests are failing. In these cases, you need to work with the contributor to help them understand the problem and fix the failing tests. To learn more about testing, please refer to [this section](/maintainer-powerups.md#testing) in the "Maintainer Power Ups" chapter. ### Code Quality Check -It is important to check for code quality and good software engineering practices when conducting code reviews. This includes checking for proper variable naming, adherence to coding standards, and ensuring that the code is easy to read and understand. It is encouraged to have a coding style guide in place to help contributors understand the coding standards of your project. +It is important to check for code quality and good software engineering practices when conducting code reviews. This includes checking for proper variable naming, adherence to coding standards, and easy-to-read and understand code. A coding style guide is encouraged to help contributors understand your project's coding standards. -There are many tools that can help you check for code quality. You can set up linting for your project to ensure there are no syntax errors or style issues. You can also set up code scanning tools to check for security vulnerabilities and other issues in the codebase. +Many tools can help you check for code quality. You can set up linting for your project to ensure no syntax errors or style issues. You can also set up code scanning tools to check for security vulnerabilities and other issues in the codebase. To learn more about these tools, please refer to [this section](/maintainer-powerups.md#code-scanning-tools) in the "Maintainer Power Ups" chapter. ### Branch Protection Rules -You can set up branch protection rules on GitHub to ensure all pull requests are reviewed before merging. Setting it up not only assures that a maintainer has reviewed all contributions but also helps to maintain the quality of the code. - -You can also set up rules to ensure multiple reviewers are required before a pull request can be merged. This can be helpful for larger projects where multiple maintainers are responsible for reviewing pull requests. +You can set up branch protection rules on GitHub to ensure all pull requests are reviewed before merging. You can also create a rule to require the number of approvals before a pull request can be merged. This not only assures that the maintainers have reviewed all contributions but also helps maintain the quality of the code, especially for larger projects. You can learn more about branch protection rules in the [official GitHub documentation](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#about-branch-protection-rules). ## Project Documentation Maintainance -Documentation is an essential part of maintaining an open source project. It helps contributors understand the project and makes it easier for them to contribute. It is important to keep the documentation up to date and ensure that it reflects the project's current state. +Documentation is an essential part of maintaining an open source project. It helps contributors understand the project and makes it easier for them to contribute. So, it is important to keep the documentation up to date and ensure it reflects the project's current state. Regularly reviewing your project's documentation is recommended to ensure it is up-to-date and accurate. You can set a schedule for once a month to review your project's documentation manually. As you review the documentation, look for ways to improve it and make it easier for contributors to understand the project. Think about times when a new contributor struggled to understand the project and update the documentation to make it easier for them to understand. -Another thing to consider in your review is running through the installation and setup instructions to ensure they are accurate and up to date. Are there any steps that are missing? Are there any steps that are no longer necessary? If so, update the documentation to reflect the project's current state. +Another thing to consider in your review is running through the installation and setup instructions to ensure they are accurate and up to date. Are there any steps that still need to be included? Are there any steps that are no longer necessary? If so, update the documentation to reflect the project's current state. If you have a more complex project, consider adding diagrams or images to help explain the project's architecture. This can help contributors understand how the project is structured and make it easier for them to contribute. diff --git a/metrics-and-analytics.md b/metrics-and-analytics.md index 26a04f4..00b4302 100644 --- a/metrics-and-analytics.md +++ b/metrics-and-analytics.md @@ -1,6 +1,6 @@ # The Power of Metrics and Analytics for New Maintainers -For new maintainers, understanding what's happening with your project and contributors as it grows can be challenging. Think of metrics and analytics like a compass and map in your maintainer journey. Understanding metrics for open source projects and your own project can help you to set goals, identify project needs, and understand your community. This chapter will guide you through understanding, leveraging, and making decisions based on these insights to create a thriving open source project. +Understanding what's happening with your project and contributors as it grows can be challenging for new maintainers. Think of metrics and analytics like a compass and map in your maintainer journey. Understanding metrics for open source projects and your own project can help you to set goals, identify project needs, and understand your community. This chapter will guide you through understanding, leveraging, and making decisions based on these insights to create a thriving open source project. ## Understanding Types of Metrics @@ -14,7 +14,7 @@ Diverse metrics offer a more complete picture of a project's health and potentia ## Setting Project Goals -Setting clear, achievable goals can help you with project management. Your goals might vary and include improving code quality, expanding the community, or streamlining issue resolution. When you set specific goals, you're better able to make decisions about prioritization and using resources (don't forget, time is a resource!). +Setting clear and achievable goals can help you with project management. can help you with project management. Your goals might vary and include improving code quality, expanding the community, or streamlining issue resolution. When you set specific goals, you're better able to make decisions about prioritization and using resources (don't forget, time is a resource!). Remember, goals for your open source project are final. They will evolve as the project grows. Metrics can inform these changes, providing insights that reveal new opportunities or challenges. For instance, if a project sets an initial goal to increase contributor numbers but later finds that engagement or quality is suffering, it might shift focus towards improving onboarding processes or documentation. @@ -62,7 +62,7 @@ An OpenSauced [Workspace](https://docs.opensauced.pizza/features/workspaces/) se To create a Workspace: -1. Log in to your [OpenSauced account](https://app.opensauced.pizza/). Once you're there, you should see your personal workspace. +1. Log in to your [OpenSauced account](https://app.opensauced.pizza/). Once you're there, click the "Workspace" dashboard, and you should see your personal workspace. 2. Click on the "Edit" button. You'll be prompted to name your workspace and add repositories. 3. Add your project's repository. 4. Click "Create Workspace" to create your Workspace. diff --git a/your-team.md b/your-team.md index 4a59eb8..6b3a872 100644 --- a/your-team.md +++ b/your-team.md @@ -1,6 +1,6 @@ # Building Your Open Source Dream Team -Managing a project in open source requires clear communication, empathy, and technical understanding. You might find that initially, you can do all or most of the work by yourself. That's great! If you want your project to grow and thrive, cultivating a diverse, motivated, and effective team around you can help you do that. This chapter looks at how to effectively collaborate with your team and offers guidance on identifying, onboarding, and empowering your open source squad. +Managing an open source project requires clear communication, empathy, and technical understanding. You might find that initially, you can do all or most of the work by yourself. That's great! If you want your project to grow and thrive, cultivating a diverse, motivated, and effective team around you can help you do that. This chapter looks at how to collaborate with your team effectively and offers guidance on identifying, onboarding, and empowering your open source squad. ## Types of Teams @@ -8,7 +8,7 @@ Creating teams on GitHub allows you to grant more permissions to a group of peop ### Triage Team -Triage teams help to efficiently handle incoming issues and pull requests. A triage team categorizes, prioritizes, and assigns issues to appropriate maintainers or contributors, reducing the maintainer's workload and ensuring timely attention to important matters. +Triage teams help handle incoming issues and pull requests efficiently. They categorize, prioritize, and assign issues to appropriate maintainers or contributors, reducing the maintainer's workload and ensuring timely attention to important matters. **Benefits**: Faster response to users, improved issue tracking, and better allocation of resources. @@ -20,7 +20,7 @@ The maintainer team shares responsibility for code reviews, bug fixes, and featu ### Documentation (Docs) Team -The docs team creates and maintains high-quality documentation for users and contributors. A dedicated documentation team ensures clear and up-to-date information is readily available, reducing support requests and confusion. +The docs team creates and maintains high-quality documentation for users and contributors. A dedicated documentation team ensures clear, up-to-date information is readily available, reducing support requests and confusion. **Benefits**: Improved user experience, easier onboarding for new contributors, and less time spent answering basic questions. @@ -32,7 +32,7 @@ The docs team creates and maintains high-quality documentation for users and con - Marketing Team - Core Team\* -**\*Just a note on Core Team**: Sometimes the maintainer team and the core team are the same. Generally speaking, a core team often focuses on broader responsibilities like strategy, governance, and community management, providing insight into the direction of the project. Maintainer teams are more likely to focus on day-to-day management and technical aspects of the project. +?> Sometimes, the Maintainer Team and the Core Team are the same. Generally speaking, a Core Team often focuses on broader responsibilities like strategy, governance, and community management, providing insight into the project's direction. The Maintainer Team is more likely to focus on the project's day-to-day management and technical aspects. ## Assembling Your A-Team: Adding New Members @@ -44,11 +44,11 @@ Just like a superhero team expands to face escalating threats, your project migh ### Scouting for Superpowers -Your search for new teammates should be deliberate and thoughtful. Look for contributors who have consistently shown their commitment and skills through active involvement in your project. Their contributions to issues, pull requests, and community discussions can help you determine if they understand the project and your vision. Other things to consider are having enthusiasm, a collaborative spirit, and alignment with your project's goals. Open source projects thrive on passion and shared purpose. +Your search for new teammates should be deliberate and thoughtful. Look for contributors who have consistently shown commitment and skills through active involvement in your project. Their contributions to issues, pull requests, and community discussions can help you determine if they understand the project and your vision. Other things to consider are having enthusiasm, a collaborative spirit, and alignment with your project's goals. Open source projects thrive on passion and shared purpose. ### Inviting Your Team -Once you've identified potential team members, extend a formal invitation. This public acknowledgment of their contributions not only shows your appreciation but also serves as an inspiration to other community members. Platforms like GitHub offer streamlined mechanisms for adding team members, making it a seamless process to officially welcome your new team members. +Once you've identified potential team members, extend a formal invitation. This public acknowledgment of their contributions not only shows your appreciation but also serves as an inspiration to other community members. Platforms like GitHub offer streamlined mechanisms for adding team members, making it a seamless process to welcome your new team members officially. ## Granting Team Permissions @@ -57,12 +57,12 @@ Each team should have a specific set of permissions that allow them to do what t ### Repository-Specific Permissions - **Read**: Allow members to view code, issues, and pull requests.
_Suitable for stakeholders, external collaborators, or those needing general visibility._ -- **Triage**: Grant permission to manage issues and pull requests (assign, label, comment, close), but not directly modify code.
_Ideal for triage teams and community managers._ -- **Write**: Allow members to push code, create branches, and open pull requests.
_Necessary for developers and maintainers actively contributing to the codebase._ +- **Triage**: Grant permission to manage issues and pull requests (assign, label, comment, close) but not directly modify code.
_Ideal for triage teams and community managers._ +- **Write**: Allow members to push code, create branches, and open pull requests.
_Necessary for developers and maintainers who are actively contributing to the codebase._ - **Maintain**: Grant broader management permissions, including deleting branches, editing protected files, and managing releases.
_Suitable for core maintainers responsible for project health._ -- **Admin**: Provide full control over the repository, including sensitive actions like deleting the repository or changing its visibility.
_Reserved for trusted individuals or those with specific administrative needs._
+- **Admin**: Provide full control over the repository, including sensitive actions like deleting or changing its visibility.
_Reserved for trusted individuals or those with specific administrative needs._
-To access your team's permissions, navigate to your team's page on GitHub and click on the "Settings" tab. From there, you can update your team's permissions in the "Member privileges" section. +To access your team's permissions, navigate to your team's page on GitHub and click the "Settings" tab. From there, you can update your team's permissions in the "Member privileges" section. Here's what it will look like in GitHub: @@ -93,13 +93,13 @@ You can see some of the options here: ### Specialization: The Key to Scale -As your project grows in complexity, the need for specialized attention in specific areas might arise. Documentation might require someone who can write for audiences at all levels of expertise, while community engagement might need a charismatic presence. Identifying these needs and recruiting contributors with relevant expertise allows you to delegate ownership and ensure all aspects of your project receive the dedicated care they deserve. +The need for specialized attention in specific areas might arise as your project grows in complexity. Documentation might require someone who can write for audiences at all levels of expertise, while community engagement might need a charismatic presence. Identifying these needs and recruiting contributors with relevant expertise allows you to delegate ownership and ensure all aspects of your project receive the dedicated care they deserve. ### Recruiting Maintainers & Team Members It is certainly possible that there's no contributor with the right skills and passion to take on a specific role. In those cases, you might need to look outside your existing community. Reach out to other projects or communities that might have individuals with the necessary expertise. -One way to look for potential maintainers is to create a [Repository Insight Page](https://docs.opensauced.pizza/features/repo-insights/) with projects with a similar tech stack. This will allow you to see who is contributing to those projects on a regular basis, their most used languages, and more. From there, you can narrow down your search to individuals who are already familiar with your project's stack and have a proven track record of contributions by adding them to a [Contributor Insight Page](https://docs.opensauced.pizza/features/contributor-insights/). Contributor Insights allows you to see more about where they're contributing, their timezone, their activity level, and more. +One way to look for potential maintainers is to create a [Repository Insight Page](https://docs.opensauced.pizza/features/repo-insights/) with projects with a similar tech stack. This will allow you to see who contributes to those projects regularly, their most used languages, and more. From there, you can narrow your search to individuals who are already familiar with your project's stack and have a proven track record of contributions by adding them to a [Contributor Insight Page](https://docs.opensauced.pizza/features/contributor-insights/). Contributor Insights allows you to see more about where they're contributing, their timezone, activity level, and more. #### Creating a Repository and a Contributor Insight Page @@ -118,9 +118,9 @@ From there, you can create a list of contributors you're interested in learning ## Adding Team Members -Once you've identified potential team members, reach out to them, let them know why you're asking them to become a team member and provide them with a clear understanding of what you expect if they accept the role. This will help them make an informed decision and ensure they can meet your expectations. +Once you've identified potential team members, reach out to them. Let them know why you're asking them to become a team member and provide them with a clear understanding of what you expect if they accept the role. This will help them make an informed decision and ensure they can meet your expectations. -To learn how to add them to your team on GitHub, check out [this guide](https://docs.github.com/en/organizations/organizing-members-into-teams/adding-organization-members-to-a-team). +Check out [this guide](https://docs.github.com/en/organizations/organizing-members-into-teams/adding-organization-members-to-a-team) to learn how to add them to your team on GitHub. ## Onboarding New Team Members @@ -131,22 +131,22 @@ Here are some things to consider: - **Roles & Responsibilities:** Clearly define the team member's role and responsibilities. This will help them to understand what they're responsible for and what they can expect from you. - **Communication:** Establish clear communication channels and expectations. This will help to ensure that everyone is on the same page and that you're able to communicate effectively. - **Goals:** Clearly define the project's goals and how the team members can contribute. This will help them to understand how they can contribute to the project's success. -- **Timeline:** Set clear expectations for the timeline. This will help them to understand what they need to do and the deadlines. +- **Timeline:** Set clear expectations for the timeline. This will help them understand what to do and the deadlines. -One way to onboard your new team members is by having clear guidelines and making it part of your documentation. If you need an idea to create one, you can take a look at the [OpenSauced Community Maintainers Guidelines](https://docs.opensauced.pizza/contributing/opensauced-maintainers-guide/community-maintainers-guide/). +One way to onboard your new team members is to have clear guidelines and include them in your documentation. If you need an idea for creating one, you can look at the [OpenSauced Community Maintainers Guidelines](https://docs.opensauced.pizza/contributing/opensauced-maintainers-guide/community-maintainers-guide/) or read [this blog post](https://dev.to/opensauced/the-missing-piece-why-your-project-needs-a-maintainer-onboarding-process-np0). ## Keeping Track of Your Team -As your team grows, it's important to keep track of your team's participation and contributions. Depending on how many people are on your team, consider creating a [Contributor Insight Page](https://docs.opensauced.pizza/features/contributor-insights/) to keep track of your team's contributions. This will allow you to see who is contributing to your project and how often and to identify when it's time to remove someone from your team. +As your team grows, it's important to keep track of your team's participation and contributions. Depending on the number of people on your team, consider creating a [Contributor Insight Page](https://docs.opensauced.pizza/features/contributor-insights/) to keep track of your team's contributions. This will allow you to see who is contributing to your project and how often, and it will help you identify when it's time to remove someone from your team. ![Team sync GIF](/assets/gif/team-sync.gif) ## Saying Farewell: Handling Team Departures -As time goes on and people's lives change, you'll find that even the most dedicated teams might face departures. Inactivity, discord with project values, or mutual agreement can lead to changes in your team. It's important to approach these situations with respect and understanding. Privately communicate the reasons behind the decision, acknowledge the individual's contributions, and express gratitude for their time and effort. Remember, fostering a positive and supportive environment, even during departures, contributes to the overall well-being of your project community. +As time passes and people's lives change, you'll find that even the most dedicated teams might face departures. Inactivity, discord with project values, or mutual agreement can lead to changes in your team. It's important to approach these situations with respect and understanding. Privately communicate the reasons behind the decision, acknowledge the individual's contributions, and express gratitude for their time and effort. Remember, fostering a positive and supportive environment, even during departures, contributes to the overall well-being of your project community. -To remove the person from your team in GitHub, check out [this guide](https://docs.github.com/en/organizations/organizing-members-into-teams/removing-organization-members-from-a-team). +Check out [this guide](https://docs.github.com/en/organizations/organizing-members-into-teams/removing-organization-members-from-a-team) on GitHub for removing the person from your team. ## Conclusion -Remember, the team is there to support you and the project and to help you achieve your goals. As you grow your team, keep in mind that you're not just adding people to your project; you're adding people to your community. Make sure that you're adding people who are aligned with your project's values and goals and who will be a positive addition to your community. +Remember, the team is there to support you and the project and to help you achieve your goals. As you grow your team, keep in mind that you're not just adding people to your project; you're adding people to your community. Make sure you're adding people who align with your project's values and goals and who will be a positive addition to your community.