Startrekzky commented on code in PR #637: URL: https://github.com/apache/incubator-devlake-website/pull/637#discussion_r1314895156
########## docs/_temp/Installation.md: ########## @@ -0,0 +1,135 @@ +--- +title: "How to Organize Devlake Projects" +sidebar_position: 1 +description: > + How to Organize Devlake Projects +--- + +## 1. Introduction +A typical team of developers works with `pull requests`, `deployments`, and `incidents` inside boards. + +Based on such, we want to measure their productivity and stability. This is how [DORA](docs/DORA.md) does that: +- Productivity: + - How many times does the team `deploy`? (a.k.a. [Deployment Frequency](docs/Metrics/DeploymentFrequency.md)) + - How fast are the `pull requests` resolved? (a.k.a. [Lead Time](docs/Metrics/LeadTimeForChanges.md)) +- Stability: + - How many `incidents` per `deploys` does the team have? (a.k.a. [Change Failure Rate](docs/Metrics/CFR.md)) + - How fast are these `incidents` solved? (a.k.a. [Median Time to Restore](docs/Metrics/MTTR.md)) + +All these questions/metrics are based on either `pull requests`, `deployments`, or `incidents`. + +But when we scale this up, a few problems arise: +- A team usually works with multiple `repositories` +- A team also might work on different projects, and we want to measure these projects separately (e.g. it is not the same to work on a big old legacy than on a greenfield) +- There may be multiple teams +- A `board` contains incidents of multiple teams or projects +- A `repository` is managed by multiple teams or projects, e.g. a monorepo +- A `pipeline` can trigger deployments in multiple repositories +- Some organizations want to measure DORA based on projects, and some want to measure it by teams + +This is where the `project` concept comes to play. + +## 2. What is a DevLake project? +In the real world, a project is something being built and/or researched to solve some problem or to open new grounds. +In software development, a project is just a grouping of something. In DevLake, a `project` is a grouping of `pull requests`, `deployments`, or `incidents`. + + + +## 3. As a team lead, how many DevLake projects do I need? + +Because of its simplicity, the concept is flexible: you decide how to arrange `pull requests`, `deployments`, and `incidents` +either by your specific projects, by teams, technology, or any other way. + +The examples below show the patterns of how to organize your projects. + +### 3.1. Use case 1: One `board` and multiple `repos` per team + +Imagine a team that develops 2 `projects` with one `board` and multiple `repositories`. +The first `project` consists of 3 `repositories` with one of them worked most of the time +The second `project` only has 2 `repositories` worked equal time among them. +The structure will look like the following: + + Review Comment: I looked at this pic and I can understand it, but I'm worried that it might be a bit complicated for users. I have a few thoughts for your reference: 1. Make all use cases more real-life. E.g, use `2 Jira boards`, `3 GitLab repos`, and `Deployments are executed via GitLab CI in each GitLab repo` to replace the current description and the wordings in the picture.  2. Convert the single image to several steps according to the Config UI workflow to reduce the cognitive load so that users can follow it step by step. An example for the pic:  -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
