| <!doctype html> |
| <html lang="en-GB" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-Configuration/HowToOrganizeDevlakeProjects"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="generator" content="Docusaurus v2.0.0-rc.1"> |
| <link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="Apache DevLake - Open-Source Dev Data Platform for Productivity RSS Feed"> |
| <link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="Apache DevLake - Open-Source Dev Data Platform for Productivity Atom Feed"><title data-rh="true">How to Organize DevLake Projects | Apache DevLake - Open-Source Dev Data Platform for Productivity</title><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://devlake.apache.org/docs/Configuration/HowToOrganizeDevlakeProjects"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="keywords" content="Engineering Productivity, Open-Source Engineering, Open-Source Integration Tools, Data Integrates Platform, Open-Source Dev Platform, Open-Source Data Integrates, DevOps Tools Integrates, Open-Source DevOps Tools"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="How to Organize DevLake Projects | Apache DevLake - Open-Source Dev Data Platform for Productivity"><meta data-rh="true" name="description" content="How to Organize DevLake Projects |
| "><meta data-rh="true" property="og:description" content="How to Organize DevLake Projects |
| "><link data-rh="true" rel="icon" href="/img/logo.svg"><link data-rh="true" rel="canonical" href="https://devlake.apache.org/docs/Configuration/HowToOrganizeDevlakeProjects"><link data-rh="true" rel="alternate" href="https://devlake.apache.org/docs/Configuration/HowToOrganizeDevlakeProjects" hreflang="en-GB"><link data-rh="true" rel="alternate" href="https://devlake.apache.org/zh/docs/Configuration/HowToOrganizeDevlakeProjects" hreflang="zh"><link data-rh="true" rel="alternate" href="https://devlake.apache.org/docs/Configuration/HowToOrganizeDevlakeProjects" hreflang="x-default"><link rel="stylesheet" href="/assets/css/styles.0a4edf75.css"> |
| <link rel="preload" href="/assets/js/runtime~main.566cb87a.js" as="script"> |
| <link rel="preload" href="/assets/js/main.c5c21f25.js" as="script"> |
| </head> |
| <body class="navigation-with-keyboard"> |
| <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus"> |
| <div role="region"><a href="#" class="skipToContent_fXgn">Skip to main content</a></div><nav class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Navigation bar toggle" class="navbar__toggle clean-btn" type="button" tabindex="0"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/logo.svg" alt="apache devlake" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/logo.svg" alt="apache devlake" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">Apache DevLake</b></a></div><div class="navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link">Docs</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/docs/Overview/Introduction">Next</a></li><li><a class="dropdown__link" href="/docs/v1.0/Overview/Introduction">v1.0 (Stable)</a></li><li><a class="dropdown__link" href="/docs/v0.21/Overview/Introduction">v0.21</a></li><li><a class="dropdown__link" href="/docs/v0.20/Overview/Introduction">v0.20</a></li><li><a class="dropdown__link" href="/docs/v0.19/Overview/Introduction">v0.19</a></li><li><a class="dropdown__link" href="/docs/v0.18/Overview/Introduction">v0.18</a></li><li><a class="dropdown__link" href="/docs/v0.17/Overview/Introduction">v0.17</a></li><li><a class="dropdown__link" href="/docs/v0.16/Overview/Introduction">v0.16</a></li><li><a class="dropdown__link" href="/docs/v0.15/Overview/Introduction">v0.15</a></li></ul></div><a class="navbar__item navbar__link" href="/livedemo/EngineeringLeads/DORA">Use Cases</a><a class="navbar__item navbar__link" href="/community/">Community</a><a class="navbar__item navbar__link" href="/team">Team</a><a class="navbar__item navbar__link" href="/blogOverview">Blog</a><a href="https://github.com/apache/devlake" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub</a><a class="navbar__item navbar__link" href="/download">Download</a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link">ASF</a><ul class="dropdown__menu"><li><a href="https://www.apache.org/" target="_blank" rel="noopener noreferrer" class="dropdown__link">Foundation</a></li><li><a href="https://www.apache.org/licenses/" target="_blank" rel="noopener noreferrer" class="dropdown__link">License</a></li><li><a href="https://www.apache.org/events/current-event" target="_blank" rel="noopener noreferrer" class="dropdown__link">Events</a></li><li><a href="https://www.apache.org/security/" target="_blank" rel="noopener noreferrer" class="dropdown__link">Security</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html" target="_blank" rel="noopener noreferrer" class="dropdown__link">Privacy</a></li><li><a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener noreferrer" class="dropdown__link">Sponsorship</a></li><li><a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener noreferrer" class="dropdown__link">Thanks</a></li></ul></div><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"><div class="navbar__search searchBarContainer_NW3z"><input placeholder="Search" aria-label="Search" class="navbar__search-input"><div class="loadingRing_RJI3 searchBarLoadingRing_YnHq"><div></div><div></div><div></div><div></div></div></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebar_njMd"><nav class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/Overview">Overview</a><button aria-label="Toggle the collapsible sidebar category 'Overview'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/GettingStarted">Getting Started</a><button aria-label="Toggle the collapsible sidebar category 'Getting Started'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--active" aria-expanded="true" href="/docs/Config UI">Config UI</a><button aria-label="Toggle the collapsible sidebar category 'Config UI'" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/Tutorial">Tutorial</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/Configuration/HowToOrganizeDevlakeProjects">How to Organize DevLake Projects</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/AzureDevOps">Azure DevOps</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/BitBucket">Bitbucket Cloud</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/BitBucketServer">Bitbucket Server/Data Center</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/CircleCI">CircleCI</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/GitHub">GitHub</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/GitLab">GitLab</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/Opsgenie">Opsgenie</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/Jenkins">Jenkins</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/Jira">Jira</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/PagerDuty">PagerDuty</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/SonarQube">SonarQube Server</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/Tapd">TAPD</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/Teambition">Teambition(WIP)</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/webhook">Webhooks</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/Zentao">Zentao</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/AdvancedMode">Blueprint Advanced Mode</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/APIKeys">API Keys</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/Configuration/TeamConfiguration">Team Configuration</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" tabindex="0" href="/docs/Configuration/Dashboards/AccessControl">Dashboard Configuration</a></div></li></ul></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/DORA">DORA</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/Metrics">Metrics</a><button aria-label="Toggle the collapsible sidebar category 'Metrics'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/DataModels">Data Models</a><button aria-label="Toggle the collapsible sidebar category 'Data Models'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/DeveloperManuals">Developer Manuals</a><button aria-label="Toggle the collapsible sidebar category 'Developer Manuals'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/Plugins">Plugins</a><button aria-label="Toggle the collapsible sidebar category 'Plugins'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="/docs/Troubleshooting">Troubleshooting</a><button aria-label="Toggle the collapsible sidebar category 'Troubleshooting'" type="button" class="clean-btn menu__caret"></button></div></li></ul></nav></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_OVgt"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item"><a class="breadcrumbs__link" itemprop="item" href="/docs/Config UI"><span itemprop="name">Config UI</span></a><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">How to Organize DevLake Projects</span><meta itemprop="position" content="2"></li></ul></nav><span class="theme-doc-version-badge badge badge--secondary">Version: Next</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>How to Organize DevLake Projects</h1></header><p>This guide provides a step-by-step approach to organizing projects in DevLake, enabling you to measure DORA metrics according to your specific use cases.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="1-what-is-a-devlake-project">1. What is a DevLake project?<a class="hash-link" href="#1-what-is-a-devlake-project" title="Direct link to heading"></a></h2><p>On a high level, a DevLake project can be viewed as a real-world project or product line. It represents a specific initiative or endeavor within the software development domain.</p><p>On a lower level, a DevLake project is a way of organizing and grouping data from different domains. DevLake uses various <a href="/docs/Overview/KeyConcepts#data-scope">data scopes</a>, such as repos, boards, cicd_scopes, and cq_projects as the 'container' to associate different types of data to a specific project. See more on this <a href="/docs/Overview/KeyConcepts#project">doc</a>.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="2-why-is-it-important-to-organize-projects">2. Why is it important to organize projects?<a class="hash-link" href="#2-why-is-it-important-to-organize-projects" title="Direct link to heading"></a></h2><p>This is crucial due to the fact that DevLake measures DORA metrics at the project level. Each project is associated with specific key entities, such as 'pull requests', 'deployments', and 'incidents', which are used to calculate the corresponding DORA metrics. Therefore, proper project organization ensures accurate and meaningful DORA metric calculations for effective analysis and evaluation.</p><p><img loading="lazy" src="/assets/images/project_pipeline-06b394bb2f3453ffd888f20affbe2d5d.png" width="2594" height="1810" class="img_ev3q"></p><blockquote><p>How are four <a href="/docs/DORA">DORA</a> metrics calculated from 'pull requests', 'deployments', and 'incidents'?</p><ul><li><a href="/docs/Metrics/DeploymentFrequency">Deployment Frequency</a>: How often does a project <code>deploys</code>?</li><li><a href="/docs/Metrics/LeadTimeForChanges">Lead Time for Changes</a>: How fast are the <code>pull requests</code> delivered?</li><li><a href="/docs/Metrics/CFR">Change Failure Rate</a>: How many <code>deployments</code> lead to <code>incidents</code>?</li><li><a href="/docs/Metrics/MTTR">Median Time to Restore</a>: How fast are <code>incidents</code> solved?</li></ul></blockquote><h2 class="anchor anchorWithStickyNavbar_LWe7" id="3-challenges-in-project-organization">3. Challenges in project organization<a class="hash-link" href="#3-challenges-in-project-organization" title="Direct link to heading"></a></h2><p>There are several challenges associated with organizing projects in DevLake due to different development practices within teams. Some of these challenges include:</p><ul><li>Managing multiple Git repos, issue boards, and CI/CD pipelines within a project.</li><li>Having a Git repo, issue board, or CI/CD pipeline associated with multiple projects, such as in the case of mono-repos or boards used to track incidents from user feedback.</li><li>Managing multiple projects within a team and the need to measure DORA metrics at the team level.</li><li>Projects contributed by multiple teams, with each team requiring the ability to measure their own DORA metrics.</li></ul><p>This document serves as a guide to address these challenges and provide assistance in effectively dealing with these diverse development practices.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="4-general-advice">4. General advice<a class="hash-link" href="#4-general-advice" title="Direct link to heading"></a></h2><h3 class="anchor anchorWithStickyNavbar_LWe7" id="41-determining-the-number-of-devlake-projects">4.1. Determining the number of DevLake projects<a class="hash-link" href="#41-determining-the-number-of-devlake-projects" title="Direct link to heading"></a></h3><p>It is advisable to create DevLake projects that align with the number of real-life projects you have.</p><p>For example, if you have a team (Team A) responsible for managing multiple projects, it is recommended to create separate DevLake projects for each individual project instead of creating a single project named 'Team A'. This approach allows for better organization and tracking of metrics specific to each project.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="42-principles-of-organizing-projects">4.2 Principles of organizing projects<a class="hash-link" href="#42-principles-of-organizing-projects" title="Direct link to heading"></a></h3><p>When organizing projects in DevLake, it is important to associate all relevant <a href="/docs/Overview/KeyConcepts#data-scope">data scopes</a>, such as repos, issue boards, and CI/CD scopes, with the corresponding DevLake project based on real-life practices.</p><p>In situations where a repo or board is shared by multiple projects in real life, it is recommended to include them in all of these projects within DevLake. This is because DevLake cannot differentiate which commits or issues belong to specific projects. Rather than excluding shared resources from DORA measurements, it is advisable to consider them in all relevant projects.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="43-measuring-dora-at-the-team-level">4.3 Measuring DORA at the team level<a class="hash-link" href="#43-measuring-dora-at-the-team-level" title="Direct link to heading"></a></h3><p>To clarify the concepts, let's define three terms:</p><ul><li><a href="/docs/Overview/KeyConcepts#project"><code>Project</code></a>: Refers to a real-world project or product line, such as Apache DevLake or Apache Spark. It focuses on the work to be done.</li><li><code>Team</code>: Represents a department, such as the 'product team' or 'engineering team'. It focuses on the people and their roles. Note that people within the same team may not always work on the same projects.</li><li><code>Project Team</code>: Comprises individuals working on a specific project.</li></ul><p>DevLake does support measuring DORA metrics at the project-team level, which is essentially the same as measuring at the project level. However, it is important to note that DevLake does not recommend measuring DORA metrics at the team level. Despite the existence of the 'DORA by team' dashboard contributed by the community. Doing so may introduce inaccuracies and dilute the significance of measuring DORA metrics from the outset.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="5-use-cases">5. Use Cases<a class="hash-link" href="#5-use-cases" title="Direct link to heading"></a></h2><p>This section demonstrates real-life practices and how they get reflected in DevLake.</p><p>Disclaimer: <em>To keep this guide shorter, some technical details are only mentioned in |
| <a href="/docs/Configuration/HowToOrganizeDevlakeProjects#41-use-case-1-apache-projects">Use Case 1</a>, |
| so if you read this page for the first time, make sure to go through them in order.</em></p><p>Note: <em>If you use webhooks, check the <a href="/docs/Configuration/HowToOrganizeDevlakeProjects#5-about-webhooks">quick note</a> about them below.</em></p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="51-use-case-1-apache-projects">5.1. Use Case 1: Apache Projects<a class="hash-link" href="#51-use-case-1-apache-projects" title="Direct link to heading"></a></h3><p>Apache Software Foundation (ASF) has and is developing many |
| <a href="https://en.wikipedia.org/wiki/List_of_Apache_Software_Foundation_projects" target="_blank" rel="noopener noreferrer">projects</a>.</p><p>To take an example we will analyze 2 <code>projects</code>: DevLake and <a href="https://spark.apache.org/" target="_blank" rel="noopener noreferrer">Spark</a>. |
| Both are independent of each other. Assume that ASF wants to check the health of the development |
| and maintenance of these projects with DORA.</p><p>DevLake manages 3 <code>repos</code>: <a href="https://github.com/apache/incubator-devlake" target="_blank" rel="noopener noreferrer">incubator-devlake</a>, |
| <a href="https://github.com/apache/devlake-website" target="_blank" rel="noopener noreferrer">devlake-website</a>, |
| and <a href="https://github.com/apache/devlake-helm-chart" target="_blank" rel="noopener noreferrer">devlake-helm-chart</a>. |
| There are many repos related to <em>Spark</em> in one way or another. To keep it simple, |
| we will also pick 3 <code>repos</code>: <a href="https://github.com/apache/spark" target="_blank" rel="noopener noreferrer">spark</a>, |
| <a href="https://github.com/apache/spark-website" target="_blank" rel="noopener noreferrer">spark-website</a>, and <a href="https://github.com/apache/incubator-livy" target="_blank" rel="noopener noreferrer">incubator-livy</a>.</p><p><img loading="lazy" src="/assets/images/project_use_case_1-9473d6310f48a48761835cb210b50117.png" width="808" height="305" class="img_ev3q"></p><p>Both projects use GitHub for storing code (including <code>pull requests</code>), <code>deployments</code> on GitHub Actions, and <code>incidents</code>.</p><p>Note: <em>To avoid confusion between DevLake as a <code>project</code> in this use case and DevLake as a platform, |
| we will use complete names i.e. <code>project DevLake</code> and <code>platform DevLake</code> respectively.</em></p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="511-organizing-projects">5.1.1. Organizing Projects<a class="hash-link" href="#511-organizing-projects" title="Direct link to heading"></a></h4><p>First, create two projects on the DevLake platform, one for DevLake and one for Spark. |
| These will represent real-world projects.</p><p><img loading="lazy" src="/assets/images/create_project_1-6acc9250dc0a4aad6225ebc8c5b2d477.png" width="1718" height="557" class="img_ev3q"> |
| <img loading="lazy" src="/assets/images/create_project_2-a1bab3ab059002352d53f2609ca9410d.png" width="830" height="357" class="img_ev3q"></p><p>Once these are created, the connections created in the following steps will be bound to them.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="512-creating-connections">5.1.2. Creating Connections<a class="hash-link" href="#512-creating-connections" title="Direct link to heading"></a></h4><p>Since all is on GitHub in this case, we can use just 1 connection with the following properties:</p><ul><li>it includes all the project's <code>repos</code></li><li>its scope includes everything we work with (i.e. <code>pull requests</code>, <code>deployments</code>, and <code>incidents</code>)</li></ul><p>If you store <code>incidents</code> on Jira, for example, you will need to create a separate connection just for them. |
| The same applies to <code>deployments</code>, a separate connection is needed in case they are stored in Jenkins (or any other host for <code>deployments</code>).</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="513-configuring-connections">5.1.3. Configuring Connections<a class="hash-link" href="#513-configuring-connections" title="Direct link to heading"></a></h4><p>This part is described in <a href="/docs/Configuration/GitHub">GitHub</a> connection configuration. Please check the <a href="/docs/Configuration/Tutorial">configuration guide</a> for configuring other data sources.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="514-using-connections">5.1.4. Using Connections<a class="hash-link" href="#514-using-connections" title="Direct link to heading"></a></h4><p>At this point, we have projects and connections created on the platform DevLake. |
| It is time to bind those connections to the projects. To do so, follow the steps described in the <a href="/docs/Configuration/Tutorial">Tutorial</a>.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="515-resulting-metrics">5.1.5. Resulting Metrics<a class="hash-link" href="#515-resulting-metrics" title="Direct link to heading"></a></h4><p>To know if the data of a project is successfully collected to your DORA Dashboard:</p><p><img loading="lazy" src="/assets/images/navigate_to_dora_1-cc59f31f0dcb5e45750e6ae972675a8b.png" width="1720" height="522" class="img_ev3q"> |
| <img loading="lazy" src="/assets/images/navigate_to_dora_2-047353792d77d9c6e828e6f13b84fbf3.png" width="1915" height="835" class="img_ev3q"></p><p>If everything goes well, you should see all the 4 charts. |
| If something is wrong, and you are puzzled as to why, check out the |
| <a href="/docs/Troubleshooting/Dashboard#debugging-dora-issue-metrics">Debugging Dora Issue Metrics</a> page.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="516-how-can-i-observe-metrics-by-project">5.1.6. How can I observe metrics by project?<a class="hash-link" href="#516-how-can-i-observe-metrics-by-project" title="Direct link to heading"></a></h4><p>In the same DORA dashboard check out this menu point: |
| <img loading="lazy" src="/assets/images/observe_metrics_by_project_panel-74cecdf33da26d2f38c6d0ea8a8de910.png" width="1902" height="395" class="img_ev3q"></p><p>The metrics should change when you select or deselect projects, representing the projects you selected.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="52-use-case-2-multiple-teams-with-distinct-projects">5.2. Use Case 2: Multiple Teams with Distinct Projects<a class="hash-link" href="#52-use-case-2-multiple-teams-with-distinct-projects" title="Direct link to heading"></a></h3><p>Consider a scenario where a company operates with several teams, each managing one or more projects. |
| For illustration, we will explore two such teams: the Payments team and the Internal Tools team. |
| Here's a simplified representation of this scenario:</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="quick-overview">Quick Overview:<a class="hash-link" href="#quick-overview" title="Direct link to heading"></a></h4><ul><li>The Payments team works on a single project: “payments”.</li><li>The Internal Tools team manages two projects: “it-legacy” and “it-new”.</li><li>Both teams use different sets of tools and boards.</li></ul><p><img loading="lazy" src="/assets/images/project_use_case_2-6ea9c31326d89a9095ff32cad07cdc13.png" width="1580" height="1256" class="img_ev3q"></p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="step-by-step-simplification">Step-by-Step Simplification:<a class="hash-link" href="#step-by-step-simplification" title="Direct link to heading"></a></h4><ol><li><strong>Define the Teams and Projects:</strong><ul><li><strong>Payments Team</strong>:<ul><li>One project: "payments". </li></ul></li><li><strong>Internal Tools Team</strong>:<ul><li>Two projects: "it-legacy" and "it-new". </li></ul></li></ul></li><li><strong>Understand the Tools</strong>:<ul><li>Assume both teams utilize GitHub for <code>repos</code> and Jenkins for CI/CD.</li><li>The <em>Payments</em> team uses Jira boards.</li><li>The <em>Internal Tools</em> team uses webhooks for reporting incidents.</li></ul></li></ol><h4 class="anchor anchorWithStickyNavbar_LWe7" id="521-organizing-projects">5.2.1. Organizing Projects<a class="hash-link" href="#521-organizing-projects" title="Direct link to heading"></a></h4><p>DORA is effective for observing the impacts of methodology changes within a team. |
| From DORA’s standpoint, the concept of distinct <code>teams</code> is not recognized; only <code>projects</code> exist. |
| Adding a <code>team</code> concept introduces unnecessary complexity without providing any substantial benefit. </p><p>In DevLake, we create three <code>projects</code>: <em>payments</em>, <em>it-legacy</em>, and <em>it-new</em>.</p><p>It is crucial to maintain <strong>atomic</strong> <code>projects</code>, representing the smallest, independent units, |
| to prevent complexity and ensure precise data representation. <strong>Atomic</strong> <code>projects</code> allow for a more flexible |
| and accurate data comparison and combination between <code>projects</code>.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="522-adding-connections">5.2.2. Adding Connections<a class="hash-link" href="#522-adding-connections" title="Direct link to heading"></a></h4><p>Create just one connection and reuse it across projects by adding data scopes. |
| This method optimizes data collection, minimizing redundancy and ensuring more efficient use of resources.</p><p>It is NOT recommended to create multiple connections, for instance, GitHub repos, as it<br> |
| <!-- -->will increase the time to collect the data due to the storage of multiple copies of shared repos in the database.</p><p>The only exception is the webhooks: <strong>we must have 1 connection per project</strong>, |
| as this is the only way DevLake can accurately assign <code>incidents</code> to the corresponding <code>project</code>.</p><p>So, in total we will have only these connections:</p><ul><li>1 connection for all GitHub <code>repos</code> to collect <code>pull requests</code></li><li>1 connection to Jenkins to collect all <code>deployments</code></li><li>1 connection to Jira to collect <code>incidents</code></li><li>2 webhook connections to collect <code>incidents</code>: 1 per each <code>project</code> that uses webhooks (<em>it-legacy</em> and <em>it-new</em>)</li></ul><p>The step-by-step <a href="/docs/Configuration/Tutorial">Configuration Guide</a> shows how to both add connections and set scopes as described in the next chapter.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="523-setting-scopes">5.2.3. Setting Scopes<a class="hash-link" href="#523-setting-scopes" title="Direct link to heading"></a></h4><p>Now, add the connections to our projects and set the scope to them:</p><p>For payments <code>project</code>: </p><ul><li>add 1 scope to GitHub connection for <em>p1...p10</em> <code>repos</code> to collect their <code>pull requests</code></li><li>add 1 scope to Jenkins for <code>deployments</code> of <em>p1...p10</em> <code>repos</code></li><li>add 1 scope to Jira to collect <code>incidents</code></li></ul><p>For it-legacy <code>project</code>:</p><ul><li>add 1 scope to GitHub for <code>repos</code> <em>it-legacy-1</em>, <em>it-legacy-2</em>, <em>it-core-1</em> and <em>it-core-2</em> to collect their <code>pull requests</code></li><li>add 1 scope to Jenkins for <code>deployments</code> of <em>it-legacy-1</em>, <em>it-legacy-2</em>, <em>it-core-1</em> and <em>it-core-2</em> <code>repos</code></li><li>include the <em>it-legacy</em> webhook for collecting <code>incidents</code></li></ul><p>For it-new <code>project</code>:</p><ul><li>add 1 scope to GitHub for <code>repos</code> <em>it-new-1</em>, <em>it-new-2</em>, <em>it-core-1</em> and <em>it-core-2</em> to collect their <code>pull requests</code></li><li>add 1 scope to Jenkins for <code>deployments</code> of <em>it-new-1</em>, <em>it-new-2</em>, <em>it-core-1</em> and <em>it-core-2</em> <code>repos</code></li><li>include the <em>it-new</em> webhook for collecting <code>incidents</code></li></ul><h4 class="anchor anchorWithStickyNavbar_LWe7" id="524-resulting-metrics">5.2.4. Resulting Metrics<a class="hash-link" href="#524-resulting-metrics" title="Direct link to heading"></a></h4><p>See <a href="/docs/Configuration/HowToOrganizeDevlakeProjects#515-resulting-metrics">5.1.5 Resulting Metrics</a></p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="6-about-webhooks">6. About Webhooks<a class="hash-link" href="#6-about-webhooks" title="Direct link to heading"></a></h2><p><strong>Assigning a UNIQUE webhook to each project is critical.</strong> This ensures that the DevLake platform |
| correctly associates the incoming data with the corresponding project through the webhook.</p><p>If you use the same webhook across multiple projects, the data sent by it <strong>will be replicated per each |
| project that uses that webhook</strong>. More information available on the <a href="/docs/Plugins/webhook">Webhook</a> page</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="7-troubleshooting">7. Troubleshooting<a class="hash-link" href="#7-troubleshooting" title="Direct link to heading"></a></h2><p>Please check out the <a href="/docs/Troubleshooting/Dashboard#debugging-dora-issue-metrics">Debugging DORA Issue Metrics</a> to debug DORA dashboard.</p><p>If you still run into any problems, please check the <a href="/docs/Troubleshooting/Configuration">Troubleshooting</a> or <a href="https://github.com/apache/incubator-devlake/issues" target="_blank" rel="noopener noreferrer">create an issue</a></p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/apache/devlake-website/edit/main/docs/Configuration/HowToOrganizeDevlakeProjects.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/Configuration/Tutorial"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Tutorial</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/Configuration/AzureDevOps"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Azure DevOps</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#1-what-is-a-devlake-project" class="table-of-contents__link toc-highlight">1. What is a DevLake project?</a></li><li><a href="#2-why-is-it-important-to-organize-projects" class="table-of-contents__link toc-highlight">2. Why is it important to organize projects?</a></li><li><a href="#3-challenges-in-project-organization" class="table-of-contents__link toc-highlight">3. Challenges in project organization</a></li><li><a href="#4-general-advice" class="table-of-contents__link toc-highlight">4. General advice</a><ul><li><a href="#41-determining-the-number-of-devlake-projects" class="table-of-contents__link toc-highlight">4.1. Determining the number of DevLake projects</a></li><li><a href="#42-principles-of-organizing-projects" class="table-of-contents__link toc-highlight">4.2 Principles of organizing projects</a></li><li><a href="#43-measuring-dora-at-the-team-level" class="table-of-contents__link toc-highlight">4.3 Measuring DORA at the team level</a></li></ul></li><li><a href="#5-use-cases" class="table-of-contents__link toc-highlight">5. Use Cases</a><ul><li><a href="#51-use-case-1-apache-projects" class="table-of-contents__link toc-highlight">5.1. Use Case 1: Apache Projects</a></li><li><a href="#52-use-case-2-multiple-teams-with-distinct-projects" class="table-of-contents__link toc-highlight">5.2. Use Case 2: Multiple Teams with Distinct Projects</a></li></ul></li><li><a href="#6-about-webhooks" class="table-of-contents__link toc-highlight">6. About Webhooks</a></li><li><a href="#7-troubleshooting" class="table-of-contents__link toc-highlight">7. Troubleshooting</a></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/GettingStarted">Getting Started</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/DataModels/DevLakeDomainLayerSchema">Data Models</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/Metrics">Engineering Metrics</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://join.slack.com/t/devlake-io/shared_invite/zt-1lkgbdmys-AU2azidzO1u~mtjlg9my7A" target="_blank" rel="noopener noreferrer" class="footer__link-item">Slack</a></li><li class="footer__item"><a href="https://github.com/apache/incubator-devlake/issues" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub Issue Tracker</a></li><li class="footer__item"><a href="https://github.com/apache/devlake-website/issues" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub Issue Tracker For Docs</a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://github.com/apache/devlake" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub</a></li><li class="footer__item"><a href="https://twitter.com/ApacheDevLake" target="_blank" rel="noopener noreferrer" class="footer__link-item">Twitter</a></li><li class="footer__item"><a class="footer__link-item" href="/community/trademark">Trademark Guidelines</a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright"> |
| <div style="margin-top: 20px"> |
| <a href="https://incubator.apache.org/" target="_blank"><img style="height:40px; margin-bottom: 10px; margin-top: 10px" alt="Apache Software Foundation" src="/img/apache-incubator.svg"></a> |
| <p style="text-align:left; font-weight: 300; font-size: 0.8em;">Apache DevLake is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.</p> |
| <p style="text-align:left; font-weight: 300; font-size: 0.8em;">Copyright ©2026 Apache DevLake, DevLake, Apache, the Apache feather logo and the Apache DevLake project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.</p> |
| </div> |
| </div></div></div></footer></div> |
| <script src="/assets/js/runtime~main.566cb87a.js"></script> |
| <script src="/assets/js/main.c5c21f25.js"></script> |
| </body> |
| </html> |
