Startrekzky commented on code in PR #634:
URL:
https://github.com/apache/incubator-devlake-website/pull/634#discussion_r1312979449
##########
docs/_temp/Installation.md:
##########
@@ -0,0 +1,64 @@
+---
+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
`issues` (a.k.a. Bugs for deployment).
+
+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 `issues` per `deploys` does the team have? (a.k.a. [Change
Failure Rate](docs/Metrics/CFR.md))
Review Comment:
Can we use incidents to replace issues here and in the following sections?
I want the users to understand that the real entities being measured in DORA
are `incidents`, a specific type of `issues` according to DevLake's abstraction.
##########
docs/_temp/Installation.md:
##########
@@ -0,0 +1,64 @@
+---
+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
`issues` (a.k.a. Bugs for deployment).
+
+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 `issues` per `deploys` does the team have? (a.k.a. [Change
Failure Rate](docs/Metrics/CFR.md))
+ - How fast are these `issues` solved? (a.k.a. [Median Time to
Restore](docs/Metrics/MTTR.md))
+
+All these questions/metrics are based on either `pull requests`,
`deployments`, or `issues`.
+
+But when we scale this up, 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
+
+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
`issues`.
+
+
+
+## 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 `issues`
+either by your specific projects, by teams, technology, or any other way.
+
+Let's consider an example:
Review Comment:
Shall we make the structure as use case 1/2/3 and etc., so that we can add
more in the future? For example:
- use case 1: the one you wrote, each team has `1 Jira board`, `x Git
repos`, and each deployment is performed within a repo
- use case 2: a more complex combination,
- each team maintains `X Jira boards for requirements`, but also shares
`Y Jira boards for bugs and incidents`.
- each team maintains `X repos for mainapps`, but also shares some `Y
repos for libraries`.
- each team maintains their own deployments for mainapps
- use case 3: a case that incidents and deployments are both from Webhook
- etc.
##########
docs/_temp/Installation.md:
##########
@@ -0,0 +1,64 @@
+---
+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
`issues` (a.k.a. Bugs for deployment).
+
+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 `issues` per `deploys` does the team have? (a.k.a. [Change
Failure Rate](docs/Metrics/CFR.md))
+ - How fast are these `issues` solved? (a.k.a. [Median Time to
Restore](docs/Metrics/MTTR.md))
+
+All these questions/metrics are based on either `pull requests`,
`deployments`, or `issues`.
+
+But when we scale this up, 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
+
+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
`issues`.
+
+
+
+## 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 `issues`
+either by your specific projects, by teams, technology, or any other way.
+
+Let's consider an example:
+- There is 1 team working on 2 projects
+- The first project consists of 3 repositories with one of them worked most of
the time
+- The second project only has 2 repos worked equal time among them
+
+
+
+Note that:
+- If instead there were 2 separate teams, the structure would remain the same.
The only thing to consider changing is the name of the project
+- The same applies to any other way of arranging the projects
+- It does not matter if a particular repository it touched more than the
others. Why? The answer is in the section below
+
+### 3.1. What am I looking for with DORA?
+TODO: explain right and wrong ways to use DORA
+
+## 4. How do we organize projects when there is data from multiple
connection(s)?
+TODO
+
+### 4.1. Webhooks
+TODO
+
+## 5. How do I know if the data of a project is successfully collected?
Review Comment:
This could be a link to the FAQ you put up earlier.
##########
docs/_temp/Installation.md:
##########
@@ -0,0 +1,64 @@
+---
+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
`issues` (a.k.a. Bugs for deployment).
+
+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 `issues` per `deploys` does the team have? (a.k.a. [Change
Failure Rate](docs/Metrics/CFR.md))
+ - How fast are these `issues` solved? (a.k.a. [Median Time to
Restore](docs/Metrics/MTTR.md))
+
+All these questions/metrics are based on either `pull requests`,
`deployments`, or `issues`.
+
+But when we scale this up, few problems arise:
+- A team usually works with multiple repositories
Review Comment:
I can think of more problems:
1. A `board` contains issues of multiple teams or projects
2. A `repository` is managed by multiple teams or projects, e.g. monorepos
3. A `CICD pipeline or job` can trigger deployments in multiple repositories
4. Some organizations want to measure DORA based on projects, and some want
to measure it by teams.
##########
docs/_temp/Installation.md:
##########
@@ -0,0 +1,64 @@
+---
+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
`issues` (a.k.a. Bugs for deployment).
+
+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 `issues` per `deploys` does the team have? (a.k.a. [Change
Failure Rate](docs/Metrics/CFR.md))
+ - How fast are these `issues` solved? (a.k.a. [Median Time to
Restore](docs/Metrics/MTTR.md))
+
+All these questions/metrics are based on either `pull requests`,
`deployments`, or `issues`.
+
+But when we scale this up, 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
+
+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
`issues`.
+
+
+
+## 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 `issues`
+either by your specific projects, by teams, technology, or any other way.
+
+Let's consider an example:
+- There is 1 team working on 2 projects
+- The first project consists of 3 repositories with one of them worked most of
the time
+- The second project only has 2 repos worked equal time among them
+
+
Review Comment:
Shall we use `incidents` and `deployments` in this diagram to keep the terms
consistent in this doc?
##########
docs/_temp/Installation.md:
##########
@@ -0,0 +1,64 @@
+---
+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
`issues` (a.k.a. Bugs for deployment).
+
+Based on such, we want to measure their productivity and stability. This is
how [DORA](docs/DORA.md) does that:
+- Productivity:
Review Comment:
This is an excellent and easy-to-understand interpretation of DORA.
--
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]
