diff --git a/docs/maintainers/maintainers-guide.md b/docs/maintainers/maintainers-guide.md new file mode 100644 index 00000000..7634d962 --- /dev/null +++ b/docs/maintainers/maintainers-guide.md @@ -0,0 +1,55 @@ +--- +id: maintainers-guide-to-open-sauced +title: 'Maintainers Guide to OpenSauced' +sidebar_label: Maintainers Guide to OpenSauced +keywords: + - maintainers + - guides +--- + +## Introduction to OpenSauced for Maintainers +OpenSauced is a platform dedicated to empowering maintainers and redefining open source contributions. We offer a GitHub-powered dashboard for tracking contributions and gaining insights into your open source projects. You can customize your Insights pages and lists with the repositories you choose and with the contributors you want to see. + +You can connect with your team and contributors through our platform and invite them to join OpenSauced. We also offer a GitHub browser extension that allows you to view your contributors' OpenSauced profiles and invite them to join OpenSauced with a single click. + +## Getting Started +To get started, you will need to create an account on OpenSauced. You can do this by visiting [app.opensauced.pizza](https://app.opensauced.pizza) and clicking the "Connect with GitHub" button. You will be prompted to sign in with your GitHub account. Once you have signed in, you will be redirected to the OpenSauced dashboard. + +## Insights: Connecting Your Repositories +OpenSauced Insights provides maintainers with a visual representation of their project's health and contributor engagement. It offers real-time data and analytics to understand contribution patterns, identify key contributors, and measure the project's growth. Insights can help you to assess team activity, understand when bottlenecks occur, identify where resource allocation is needed, plan and identify key contributors, understand contributor churn, or spot emerging trends. + +Insights features allow you to: +- track the contributions of a specific team, a specific repository, or group of repositories +- view the number of pull requests that are open, closed, in draft, and merged +- view the average number of days it takes for a pull request to be merged (PR velocity) +- identify the top contributors to your project +- identify the current activity level and trends in activity of your contributors + + +### Creating a New Insight Page +To connect your repositories, click the "Insights" tab on the dashboard. You will be redirected to a page where you can create your new insight page. + +There are two ways to add repositories to your Insight Page: +1. **Sync GitHub Organization**. Syncing your GitHub organization is a good idea for someone who seeks a comprehensive, unified view of your organization's open source project activities and trends, enabling streamlined management, strategic decision-making, and efficient allocation of resources across multiple repositories. +2. **Connect Individual Repositories**. Connecting individual repositories is a good idea for someone who wants to track the contributions of a specific repository or group of repositories. For example, you might want to track projects you maintain that are not under the same org or you may want to track projects that align with your team's objectives. + +![sync team gif](../../static/img/team-sync-insights.gif) + +### Using Your Insights Page +Once you have connected your repositories, you will be redirected to your Insight Page. Here you will see a dashboard with an overview of the repositories and the contributors who have contributed to them. + +There are three tabs that provide you with more information on these repositories. + +#### Reports +The reports tab allows paid users to filter for more information about their repositories over the last thirty days and to generate a Downloadable CSV. Filters include: Minumum 5 Contributors, Recent, Most Active, and Spammed. + +#### Repositories +The repositories tab allows you to view more detailed information on each of the repositories, including Activity, PR Overview, PR Velocity, Spam, Contributors, and activity over the last 30 days. To learn more about these features, see [Understanding Insights Data](#understanding-insights-data). + +![repositories tab](../../static/img/repos-insights.png) + +#### Contributors +The contributors tab allows you to view more detailed information on each of the contributors, including Activity, Repositorites, the date of their last contribution, time zone, and number of contributions. + +To learn more about your contributors, you can select them and add them to a list. + diff --git a/docs/maintainers/understanding-insights.md b/docs/maintainers/understanding-insights.md new file mode 100644 index 00000000..53b73c6c --- /dev/null +++ b/docs/maintainers/understanding-insights.md @@ -0,0 +1,45 @@ +--- +id: understanding-insights +title: 'Interpreting Insights Data' +sidebar_label: Maintainers Guide Understanding Insights +keywords: + - maintainers + - guides +--- + +Once your repositories are connected, it's time to understand the data provided in your Insight Page. Understanding this data is key to effectively managing your projects and contributors. + +## Understanding Insights Repository Data + +### Analyzing Contribution Trends +Discover patterns in contributions over time. Look for spikes or drops in activity, and correlate these with specific events or milestones. This can help you understand what drives engagement in your projects. + +### Monitoring Pull Request (PR) Activity +Knowing the status of PRs (open, closed, draft, merged) helps in understanding the workflow efficiency and backlog. High volumes of open or draft PRs might indicate a need for more resources or a revision of your review process. Conversely, a steady flow of merged PRs can a healthy, active development process. + +### Measuring and Improving PR Velocity +Track how quickly PRs are being merged. The average time taken for PRs to merge is a critical metric for understanding the efficiency of the code review and deployment process. Longer PR merge times might signal issues in the review process, resource allocation, or could indicate complex code changes that require more thorough checks. Use this data to set benchmarks and identify opportunities for streamlining your review and integration processes. + +## Understanding Insights Contributor Data + +### Identifying and Engaging with Key Contributors +Recognizing key contributors helps in understanding who the most active and influential members of the project are. Consider reaching out to them for deeper collaboration, or acknowledging their efforts to keep them motivated and engaged. + +### Tracking and Responding to Contributor Activity Levels +Tracking how active contributors are and the trends in their activity level is crucial for project health. Understanding the activity patterns of contributors helps in assessing their engagement and reliability. Regular contributors are often more familiar with the project and can be more dependable for critical tasks. + +Notice the ebbs and flows in individual contributors’ activity. A decline in a normally active contributor’s engagement could indicate burnout or dissatisfaction, while a surge in activity might be tied to recent changes or enhancements in the project. Tracking activity levels can help you in managing team burnout, understanding resource needs, and spotting potential issues before they escalate. + +#### Activity Levels Across Repositories +This indicates the breadth of a contributor's involvement in open source projects. A contributor active across multiple repositories might bring diverse experiences and ideas, but may also have divided attention. Alternatively, a contributor active in a single repository might be more focused and familiar with the project. + +### Understanding Activity Levels Over Time +Past activity levels can be a predictor of future contributions. Regular past contributions might suggest continued involvement. However, a contributor who has been inactive for a while might be less likely to contribute in the future. + +Trends in activity levels and contributions can be indicators of the overall health of the project community. A decline in activity might signal issues that need addressing to keep the community vibrant and engaged. + +### Using Programming Language Data +Awareness of the programming languages a contributor is comfortable with enables maintainers to assign tasks more effectively, ensuring that contributors are working in areas where they are most skilled and interested. This can help in identifying contributors for specific tasks or projects. + +### Creating Opportunities +Understanding who contributes to what and when can help maintainers manage team dynamics, ensuring that workloads are balanced and contributors are working in areas that match their skills and interests. Identifying less experienced contributors who are active and showing potential can lead to mentorship opportunities, helping to grow the project’s contributor base. \ No newline at end of file diff --git a/static/img/repos-insights.png b/static/img/repos-insights.png new file mode 100644 index 00000000..abce861d Binary files /dev/null and b/static/img/repos-insights.png differ diff --git a/static/img/team-sync-insights.gif b/static/img/team-sync-insights.gif new file mode 100644 index 00000000..61344f8d Binary files /dev/null and b/static/img/team-sync-insights.gif differ