Skip to content

Commit b178d0f

Browse files
shenxianpengshenxianpeng
authored
docs: update spec by refining content and table formatting (#16)
This PR updates the documentation for the DevOps Maturity Specification by refining content and table formatting, updating FAQ phrasing, and adjusting configuration details. Key changes include: Adding a new details shortcode snippet in HTML for expandable content. Revising and reformatting the main index markdown to improve clarity with updated headings, table formatting (with footnotes), and FAQ sections. Updating configuration titles and descriptions in config.yaml for both English and Chinese sections.
1 parent e0f5b65 commit b178d0f

4 files changed

Lines changed: 124 additions & 186 deletions

File tree

‎config.yaml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@ languages:
2323
params:
2424
weight: 1
2525
languageName: "English"
26-
title: DevOps Maturity
27-
description: DevOps Maturity Specification — assess, improve, and showcase your DevOps maturity.
26+
title: DevOps Maturity Specification
27+
description: Assess, improve, and showcase your DevOps maturity — across teams and organizations.
2828
actions:
2929
- label: Quick Summary
3030
url: '#summary'
@@ -38,8 +38,8 @@ languages:
3838
params:
3939
weight: 2
4040
languageName: "中文"
41-
title: DevOps 成熟度
42-
description: DevOps 成熟度规范 - 评估、改进和展示你的 DevOps 成熟度。
41+
title: DevOps 成熟度规范
42+
description: 评估、改进和展示你的 DevOps 成熟度 — 跨团队和组织。
4343
actions:
4444
- label: 概述
4545
url: '#概述'

‎content/_index.md‎

Lines changed: 69 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,11 @@ layout: single
88

99
## Summary
1010

11-
DevOps Maturity Specification provides guidelines for DevOps best practices, aiming to enhance collaboration, automation, and efficiency across software development and operations.
11+
### What is the DevOps Maturity Specification?
1212

13-
## Key Points
13+
The DevOps Maturity Specification is a set of guidelines and criteria designed to help organizations assess and improve their DevOps practices. It provides a structured approach to evaluate key areas such as Basics, Quality, Security, Supply Chain Security, Analysis, and Reporting. The specification is intended to align with best practices and provide a framework for continuous improvement within the DevOps community.
14+
15+
### Key Points
1416

1517
- **Purpose**: Help organizations and teams assess DevOps practices, align on best practices, and drive continuous improvement.
1618
- **Scope**: Covers key DevOps domains including build, testing, security, supply chain, analysis, and reporting.
@@ -22,32 +24,33 @@ DevOps Maturity Specification provides guidelines for DevOps best practices, aim
2224

2325
## Specification
2426

25-
| **Category** | **Code**| **Criteria** |**Req.**|
26-
|--------------------|----------|------------------------------------------------------------|--------|
27-
| Basics | D101 | [Branch Builds](#d101-branch-builds) | 🟢 |
28-
| | D102 | [Pull Request Builds](#d102-pull-request-builds) | 🟢 |
29-
| | D103 | [Clean Build Environments](#d103-clean-build-environments) | 🟡 |
30-
| Quality | D201 | [Unit Testing](#d201-unit-testing) | 🟢 |
31-
| | D202 | [Functional Testing](#d202-functional-testing) | 🟢 |
32-
| | D203 | [Performance Testing](#d203-performance-testing) | 🟡 |
33-
| | D204 | [Code Coverage](#d204-code-coverage) | 🟡 |
34-
| | D205 | [Accessibility Testing](#d205-accessibility-testing) | 🟡 |
35-
| Security | D301 | [Security Scanning](#d301-security-scanning) | 🟢 |
36-
| | D302 | [License Scanning](#d302-license-scanning) | 🟡 |
37-
| Supply Chain Security| D401 | [Documented Build Process](#d401-documented-build-process) | 🟢 |
38-
| | D402 | [CI/CD as Code](#d402-ci-cd-as-code) | 🟢 |
39-
| | D403 | [Artifact Signing](#d403-artifact-signing) | 🟡 |
40-
| | D404 | [Dependency Pinning](#d404-dependency-pinning) | 🟡 |
41-
| Analysis | D501 | [Static Code Analysis](#d501-static-code-analysis) | 🟡 |
42-
| | D502 | [Dynamic Code Analysis](#d502-dynamic-code-analysis) | 🟡 |
43-
| | D503 | [Code Linting](#d503-code-linting) | 🟡 |
44-
| Reporting | D601 | [Notifications & Alerts](#d601-notifications--alerts) | 🟢 |
45-
| | D602 | [Attached Reports](#d602-attached-reports) | 🟡 |
46-
47-
- 🟢 Must-Have (Weight: 1)
48-
- 🟡 Nice-to-Have (Weight: 0.5)
49-
50-
_Proposed a new criterion?_ Please [open an issue](https://github.com/devops-maturity/spec/issues).
27+
| **Category** | **Code**[^1]| **Criteria**[^2] |**Req.**[^3]|
28+
|--------------------|----------|--------------------------------|--------|
29+
| Basics | D101 | Branch Builds | 🟢 |
30+
| | D102 | Pull Request Builds | 🟢 |
31+
| | D103 | Clean Build Environments | 🟡 |
32+
| Quality | D201 | Unit Testing | 🟢 |
33+
| | D202 | Functional Testing | 🟢 |
34+
| | D203 | Performance Testing | 🟡 |
35+
| | D204 | Code Coverage | 🟡 |
36+
| | D205 | Accessibility Testing | 🟡 |
37+
| Security | D301 | Security Scanning | 🟢 |
38+
| | D302 | License Scanning | 🟡 |
39+
| Supply Chain Security| D401 | Documented Build Process | 🟢 |
40+
| | D402 | CI/CD as Code | 🟢 |
41+
| | D403 | Artifact Signing | 🟡 |
42+
| | D404 | Dependency Pinning | 🟡 |
43+
| Analysis | D501 | Static Code Analysis | 🟡 |
44+
| | D502 | Dynamic Code Analysis | 🟡 |
45+
| | D503 | Code Linting | 🟡 |
46+
| Reporting | D601 | Notifications & Alerts | 🟢 |
47+
| | D602 | Attached Reports | 🟡 |
48+
49+
[^1]: A criteria ID code is a unique identifier assigned to specific criteria. For more details, see the [Code Map](#code-map).
50+
[^2]: Detailed information on each criteria can be found in the [Criteria Details](#criteria-details) section.
51+
[^3]: Required Levels: 🟢 Must-Have (Weight: 1), 🟡 Nice-to-Have (Weight: 0.5).
52+
53+
_Proposed a new criteria?_ Please [open an issue](https://github.com/devops-maturity/spec/issues).
5154

5255
## Badge Levels
5356

@@ -82,90 +85,51 @@ Your score will generate one of the following badges:
8285

8386
## Criteria Details
8487

85-
#### D101 Branch Builds
86-
87-
Supports builds from any specific branch, not just the `main` branch.
88-
89-
#### D102 Pull Request Builds
90-
91-
Supports building pull requests (PRs), not limited to direct pushes to branches.
92-
93-
#### D103 Clean Build Environments
94-
95-
Supports building in clean environments, such as containers or virtual machines (VMs).
96-
97-
#### D201 Unit Testing
98-
99-
Supports unit testing, including unit or component-level tests.
100-
101-
#### D202 Functional Testing
102-
103-
Supports functional testing, such as integration or end-to-end (E2E) tests.
104-
105-
#### D203 Performance Testing
106-
107-
Supports performance testing, including load, stress, or throughput testing.
108-
109-
#### D204 Code Coverage
110-
111-
Supports measuring code coverage, including line, branch, or function coverage.
112-
113-
#### D205 Accessibility Testing
114-
115-
Supports accessibility testing for standards compliance, such as WCAG.
116-
117-
#### D301 Security Scanning
118-
119-
Supports security scanning, including SAST (Static Application Security Testing) and DAST (Dynamic Application Security Testing).
120-
121-
#### D302 License Scanning
122-
123-
Supports license scanning using tools like SPDX, FOSSology, or license-checkers.
124-
125-
#### D401 Documented Build Process
88+
{{< details title="Click to expand criteria details" >}}
89+
90+
| **Code** | **Criteria** | **Description** |
91+
| ------ | ------------------------ | ------------------------------------------ |
92+
| D101 | Branch Builds | Supports builds from any specific branch, not just the `main` branch. |
93+
| D102 | Pull Request Builds | Supports building pull requests (PRs), not limited to direct pushes to branches. |
94+
| D103 | Clean Build Environments | Supports building in clean environments, such as containers or VMs. |
95+
| D201 | Unit Testing | Supports unit testing, including unit or component-level tests. |
96+
| D202 | Functional Testing | Supports functional testing, such as integration or end-to-end (E2E) tests. |
97+
| D203 | Performance Testing | Supports performance testing, including load, stress, or throughput testing.|
98+
| D204 | Code Coverage | Supports measuring code coverage, including line, branch, or function coverage.|
99+
| D205 | Accessibility Testing | Supports accessibility testing for standards compliance, such as WCAG.|
100+
| D301 | Security Scanning | Supports security scanning, including SAST and DAST. |
101+
| D302 | License Scanning | Supports license scanning using tools like SPDX, FOSSology, or license-checkers.|
102+
| D401 | Documented Build Process | Provides a documented build process, including build steps or reproducibility.|
103+
| D402 | CI/CD as Code | Supports CI/CD workflows defined as code, such as pipeline-as-code. |
104+
| D403 | Artifact Signing | Supports artifact signing to ensure authenticity and integrity. |
105+
| D404 | Dependency Pinning | Supports dependency pinning or version locking for reproducible builds. |
106+
| D501 | Static Code Analysis | Supports static analysis tools like SonarQube, Polaris, or similar. |
107+
| D502 | Dynamic Code Analysis | Supports dynamic analysis, including runtime behavior analysis or fuzz testing.|
108+
| D503 | Code Linting | Supports code linting using tools like ESLint, Prettier, or pre-commit hooks.|
109+
| D601 | Notifications & Alerts | Supports notification systems such as email or Slack alerts. |
110+
| D602 | Attached Reports | Supports attaching detailed reports to builds, like test results or coverage.|
111+
112+
{{< /details >}}
126113

127-
Provides a documented build process, including build steps, manifests, or reproducibility details.
128-
129-
#### D402 CI/CD as Code
130-
131-
Supports CI/CD workflows defined as code, such as pipeline-as-code or infrastructure-as-code.
132-
133-
#### D403 Artifact Signing
134-
135-
Supports artifact signing (e.g., with PGP or GPG) to ensure authenticity and integrity.
136-
137-
#### D404 Dependency Pinning
138-
139-
Supports dependency pinning or version locking to ensure reproducible builds.
140-
141-
#### D501 Static Code Analysis
142-
143-
Supports static code analysis tools such as SonarQube, Polaris, or similar.
144-
145-
#### D502 Dynamic Code Analysis
146-
147-
Supports dynamic analysis, including runtime behavior analysis or fuzz testing.
148-
149-
#### D503 Code Linting
150-
151-
Supports code linting using tools like ESLint, Prettier, or pre-commit hooks.
152-
153-
#### D601 Notifications & Alerts
114+
---
154115

155-
Supports notification systems such as email or Slack alerts.
116+
## FAQ
156117

157-
#### D602 Attached Reports
118+
### What is the difference between OpenSSF Best Practices and DevOps Maturity?
158119

159-
Supports attaching detailed reports to builds, such as test results or coverage metrics.
120+
[OpenSSF Best Practices](https://www.bestpractices.dev/) targets open source projects across the entire software development lifecycle, while DevOps Maturity focuses specifically on DevOps practices applicable to both open source and internal enterprise projects. DevOps Maturity provides both a web UI and a CLI for automatic maturity scoring. In contrast, OpenSSF Best Practices only offers a web-based SaaS and does not support internal deployment.
160121

161-
---
122+
### What is the difference between DevOps Maturity Model and DevOps Maturity Specification?
162123

163-
## FAQ
124+
The DevOps Maturity Model is a conceptual framework that outlines the stages of DevOps adoption and maturity, while the DevOps Maturity Specification provides a detailed, actionable set of criteria and guidelines for assessing and improving DevOps practices.
164125

165-
### What tools can be used to calculate your score?
126+
### How can I contribute to the DevOps Maturity Specification?
166127

167-
You can use [devops-maturity](https://github.com/devops-maturity/devops-maturity), which supports web UI and CLI to calculate your score automatically.
128+
You can contribute by proposing new criteria, features, or reporting bugs. Please [open an issue](https://github.com/devops-maturity/spec/issues) or [create a pull request](https://github.com/devops-maturity/spec/pulls) on GitHub. We welcome contributions from the community!
168129

169-
### What is the difference between OpenSSF Best Practices and DevOps Maturity?
130+
### How can I use the DevOps Maturity Specification in my organization?
170131

171-
[OpenSSF Best Practices](https://www.bestpractices.dev/) targets open source projects across the entire software development lifecycle, while DevOps Maturity focuses specifically on DevOps practices applicable to both open source and internal enterprise projects. DevOps Maturity provides both a web UI and a CLI for automatic maturity scoring. In contrast, OpenSSF Best Practices only offers a web-based SaaS and does not support internal deployment.
132+
You can integrate the DevOps Maturity Specification into your organization's DevOps practices by:
133+
- Using the criteria to assess your current DevOps maturity level.
134+
- Implementing the recommended criteria to improve your DevOps processes.
135+
- Utilizing tools like [devops-maturity](https://github.com/devops-maturity/devops-maturity) to calculate maturity scores and generate badges automatically.

0 commit comments

Comments
 (0)