Skip to content

Commit 904f7ef

Browse files
author
xibz
committed
add definitions.md
This commit adds the foundation for definitions to give a common semantics across the various concepts within the SDLC. This commit explicitly starts with 'build'. Signed-off-by: xibz <[email protected]>
1 parent ce1cf8d commit 904f7ef

File tree

1 file changed

+208
-0
lines changed

1 file changed

+208
-0
lines changed

‎content/en/docs/primer/definitions.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# CDEvents Concepts and Definitions
2+
3+
This document defines common concepts and ideas used across the SDLC (software
4+
development lifecycle). By establishing a shared vocabulary, it ensures that
5+
tools leveraging CDEvents use a consistent language and adhere to common
6+
definitions for seamless interoperability across different toolsets.
7+
8+
## 🏗️ Build
9+
10+
A **build** is the automated process of transforming **source code** and
11+
**resources** into an **executable artifact** that can be tested, deployed, or
12+
distributed.
13+
14+
This artifact may be a binary, a container image, a static website bundle, or
15+
even a deployable infrastructure definition like Kubernetes manifests.
16+
17+
---
18+
19+
### 🧩 What Are “Resources”?
20+
21+
Resources are any **non-executable assets** required to complete, package, or
22+
run a system. These include:
23+
24+
- **Static assets**: images, fonts, CSS, markdown
25+
- **Configuration files**: YAML, JSON, XML, `.env`
26+
- **Templates**: HTML, Handlebars, Jinja
27+
- **Schemas / contracts**: OpenAPI specs, GraphQL schemas
28+
- **Localization files**: `.po`, `.mo`, `.json` for locale strings
29+
- **Compiled non-code assets**: `.wasm` from `.wat`, `.pdf` from `.md`
30+
31+
Some builds may not involve source code at all — such as infrastructure-as-code
32+
templates, documentation bundles, or configuration files that need packaging,
33+
versioning, or transformation.
34+
35+
---
36+
37+
### 🔧 What Constitutes a Build?
38+
39+
A typical build process may include:
40+
41+
- 🔄 **Compiling code**: e.g., `.java → .class`, `.ts → .js`
42+
- 📦 **Bundling dependencies**: e.g., NPM modules, Maven packages
43+
- 📦 **Packaging artifacts**: e.g., JAR, Docker image, zip file
44+
- 🏷️ **Versioning**: tagging or stamping artifacts
45+
- 🧪 **Static analysis** *(pre-build or during build)*
46+
- 🧬 **Configuration templating**: injecting environment-specific variables
47+
48+
---
49+
50+
### 🧪 Build Examples and Edge Cases
51+
52+
| **Type** | **Is it a Build?** | **Example** | **Notes** |
53+
|-------------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------|
54+
| Java code to JAR | ✅ Yes | Compile `.java` to `.jar` | Traditional code compilation |
55+
| Markdown to HTML | ✅ Yes | Static site generation (e.g., Hugo) | Transforms content into deployable form |
56+
| CSS/JS minification | ✅ Yes | Bundle & minify assets | Common in front-end workflows |
57+
| Copying static files | ❌ Not typically | File copying without transformation | Often part of build but not a build by itself |
58+
| Helm template to Kubernetes | ✅ Yes | `helm template` to render manifests | Generates deployable infra config |
59+
| Helm chart packaging | ✅ Yes | `helm package` to create `.tgz` chart | Versioned artifact used in CI/CD pipelines |
60+
| Helm deployment | ❌ No | `helm install` or `upgrade` | Deployment, not artifact creation |
61+
62+
---
63+
64+
### 🧰 Tool-Specific Considerations
65+
66+
| **Tool** | **Definition of Build** |
67+
|------------------|-------------------------------------------------------------------|
68+
| Jenkins | A "build" typically refers to a job run (can be compile, test, etc.) |
69+
| GitHub Actions | No strict definition — "build" is defined by your workflow steps |
70+
| GitLab CI/CD | Often treated as a named stage (e.g., `build`, `test`, `deploy`) |
71+
| Spinnaker | Uses "bake" or "artifact" stages, and may trigger builds externally |
72+
73+
---
74+
75+
## 🧪 Test
76+
77+
A **test** is the automated process of executing code, configuration, or system
78+
components to **verify correctness, quality, and adherence to specified
79+
requirements**. It provides feedback on whether a system behaves as expected
80+
under various conditions.
81+
82+
---
83+
84+
### 🔬 What Are “Test Assets”?
85+
86+
Test assets encompass any components, data, or environments specifically
87+
designed or required to perform testing. These include:
88+
89+
- **Test Cases**: Specific inputs, execution steps, and expected outputs or behaviors.
90+
- **Test Suites**: Collections of related test cases, often grouped by functionality or type.
91+
- **Test Data**: Data used as input for test cases (e.g., mock data, sanitized production data).
92+
- **Test Environments**: Specific configurations of hardware, software, and network settings where tests are executed.
93+
- **Test Frameworks**: Libraries or tools that facilitate writing, executing, and reporting tests (e.g., JUnit, Pytest, Selenium, Jest).
94+
- **Test Reports**: Summaries of test execution, including pass/fail status, errors, and performance metrics.
95+
96+
---
97+
98+
### 📊 What Constitutes a Test?
99+
100+
A typical automated test process may include:
101+
102+
- 🚀 **Execution**: Running one or more test cases against the system under test.
103+
- 🔍 **Assertion**: Comparing actual outputs or behaviors against expected outcomes.
104+
- ✅ **Validation**: Determining whether the test passed or failed based on assertions.
105+
- 📝 **Reporting**: Generating logs, metrics, and reports of test results.
106+
- ⚙️ **Setup/Teardown**: Preparing the test environment before execution and cleaning up resources afterward.
107+
- 📈 **Coverage Analysis**: Measuring the extent to which the code or system has been exercised by tests.
108+
109+
---
110+
111+
### 🧪 Test Examples and Edge Cases
112+
113+
| **Type** | **Is it a Test?** | **Example** | **Notes** |
114+
|------------------------------|-------------------|-----------------------------------------------------|-------------------------------------------------------------------|
115+
| Unit Test | ✅ Yes | JUnit tests for a Java class | Verifies individual components in isolation |
116+
| Integration Test | ✅ Yes | API tests verifying service interaction | Checks communication and data flow between modules |
117+
| Functional/Acceptance Test | ✅ Yes | Selenium UI tests for a web application | Validates end-to-end user flows against requirements |
118+
| Performance Test | ✅ Yes | JMeter load test on an API endpoint | Assesses system responsiveness and stability under load |
119+
| Security Scan (SAST/DAST) | ✅ Yes | SonarQube static analysis, OWASP ZAP dynamic scan | Identifies vulnerabilities (often automated in CI/CD) |
120+
| Contract Test | ✅ Yes | Pact tests between consumer and provider APIs | Ensures API compatibility between services |
121+
| Accessibility Test | ✅ Yes | Automated WCAG compliance checks (e.g., Axe) | Verifies usability for people with disabilities |
122+
| Manual Exploratory Testing | ❌ No | Human tester exploring application functionality | Not an automated process, thus outside CDEvents scope |
123+
| Code Linting/Formatting | ❌ No | `prettier --check`, `gofmt` | Focuses on code style and consistency, not functional correctness |
124+
| Dependency Vulnerability Scan| ❌ No | `npm audit`, Snyk scan | Scans for known vulnerabilities in dependencies, not functional test of *your* code |
125+
126+
---
127+
128+
### 🧰 Tool-Specific Considerations
129+
130+
| **Tool** | **Definition of Test** |
131+
|------------------|----------------------------------------------------------------|
132+
| Jenkins | Defined by pipeline steps that execute test commands (e.g., `mvn test`) |
133+
| GitHub Actions | Typically a job or step that runs test commands or frameworks |
134+
| GitLab CI/CD | Often a dedicated job stage (e.g., `test` stage) with test execution commands |
135+
| Azure DevOps | "Test Plans" or "Test Pipelines" that run automated tests and publish results |
136+
| SonarQube | Primarily for static analysis and code quality, but often integrated with test results for coverage |
137+
| Jest/JUnit/Pytest| Frameworks for writing and executing tests within codebases |
138+
| Selenium/Cypress | Frameworks for automated browser-based functional testing |
139+
140+
---
141+
142+
## 💾 Store
143+
144+
**Storing** is the automated process of persistently saving, managing, and
145+
making accessible any **artifact, data, or metadata** generated or consumed
146+
during the SDLC. It ensures that necessary components and information are
147+
retrievable for future use, auditing, or deployment.
148+
149+
---
150+
151+
### 📦 What Are “Stored Assets”?
152+
153+
Stored assets encompass any durable output or input that is preserved across
154+
the SDLC. These include:
155+
156+
- **Build Artifacts**: Executables, container images, packages, libraries (e.g., JARs, WARs, Docker images, npm packages).
157+
- **Source Code**: The versioned codebase managed in a Version Control System (VCS).
158+
- **Configuration**: Environment-specific settings, deployment manifests, or infrastructure-as-code definitions.
159+
- **Test Results**: Reports, logs, and metrics from test executions.
160+
- **Logs**: Runtime logs from applications or infrastructure.
161+
- **Metrics**: Performance, usage, or health data collected over time.
162+
- **Documentation**: Generated or manually created documentation.
163+
- **Snapshots/Backups**: Point-in-time copies of databases or systems.
164+
165+
---
166+
167+
### 🗄️ What Constitutes Storing?
168+
169+
A typical automated storing process may include:
170+
171+
- ⬆️ **Publishing/Uploading**: Transferring an asset to a designated repository or storage location.
172+
- 🏷️ **Tagging/Versioning**: Assigning unique identifiers or metadata to stored assets for traceability.
173+
- 📦 **Indexing**: Cataloging assets within a repository for efficient searching and retrieval.
174+
- 🔐 **Access Control**: Applying permissions to regulate who can access or modify stored assets.
175+
- 🧹 **Retention/Cleanup**: Managing the lifecycle of stored assets, including deletion policies.
176+
- 🔄 **Replication**: Copying assets to multiple locations for redundancy or distribution.
177+
- 🔗 **Linking**: Establishing relationships between stored assets and other SDLC events (e.g., linking an artifact to the build that produced it).
178+
179+
---
180+
181+
### 💾 Store Examples and Edge Cases
182+
183+
| **Type** | **Is it Storing?** | **Example** | **Notes** |
184+
|------------------------------------|--------------------|-----------------------------------------------------|-------------------------------------------------------------------|
185+
| Push Docker Image to Registry | ✅ Yes | `docker push myrepo/myapp:1.0` | Persistently saves a container image for distribution |
186+
| Upload JAR to Maven Repository | ✅ Yes | `mvn deploy` to Artifactory | Stores a compiled library for dependency management |
187+
| Commit Code to Git Repository | ✅ Yes | `git push origin main` | Persists source code and its history |
188+
| Save Test Results to Database | ✅ Yes | Storing JUnit XML reports in a test management system | Preserves test outcomes for analysis and auditing |
189+
| Upload Build Logs to Object Storage| ✅ Yes | Uploading CI/CD pipeline logs to S3 | Archiving diagnostic information |
190+
| Deploying Application to Server | ❌ No | `kubectl apply -f deployment.yaml` | This is deployment/execution, not just persistent storage of an artifact |
191+
| Caching Build Dependencies | ❌ No | Local Maven `.m2` repository cache | Temporary storage for performance, not persistent distribution |
192+
| Downloading a Dependency | ❌ No | `npm install` | Retrieval from storage, not the act of storing |
193+
| Writing a Log File to Local Disk | ❌ No | `logger.info("message")` to a local file | Local/temporary persistence; "storing" implies a managed, accessible repository |
194+
195+
---
196+
197+
### 🧰 Tool-Specific Considerations
198+
199+
| **Tool** | **Definition of Store** |
200+
|------------------|------------------------------------------------------------------|
201+
| Artifactory/Nexus| Dedicated artifact repositories for various package types (Maven, npm, Docker, etc.) |
202+
| Docker Registry | Stores and manages Docker container images |
203+
| Git/GitHub/GitLab| Version Control Systems that store source code and its history |
204+
| Amazon S3/Azure Blob Storage/GCS | Object storage services used for archiving logs, backups, or raw data |
205+
| Kubernetes | Can store configuration via ConfigMaps/Secrets, but not typically "artifacts" |
206+
| Helm Chart Museum| Stores and serves Helm charts |
207+
| Test Management Systems (e.g., TestRail) | Stores test cases, test runs, and results for manual and automated tests |
208+

0 commit comments

Comments
 (0)