Skip to content

add definitions.md #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

add definitions.md #53

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 208 additions & 0 deletions content/en/docs/primer/definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,208 @@
# CDEvents Concepts and Definitions

This document defines common concepts and ideas used across the SDLC (software
development lifecycle). By establishing a shared vocabulary, it ensures that
tools leveraging CDEvents use a consistent language and adhere to common
definitions for seamless interoperability across different toolsets.

## 🏗️ Build

A **build** is the automated process of transforming **source code** and
**resources** into an **executable artifact** that can be tested, deployed, or
distributed.

This artifact may be a binary, a container image, a static website bundle, or
even a deployable infrastructure definition like Kubernetes manifests.

---

### 🧩 What Are “Resources”?

Resources are any **non-executable assets** required to complete, package, or
run a system. These include:

- **Static assets**: images, fonts, CSS, markdown
- **Configuration files**: YAML, JSON, XML, `.env`
- **Templates**: HTML, Handlebars, Jinja
- **Schemas / contracts**: OpenAPI specs, GraphQL schemas
- **Localization files**: `.po`, `.mo`, `.json` for locale strings
- **Compiled non-code assets**: `.wasm` from `.wat`, `.pdf` from `.md`

Some builds may not involve source code at all — such as infrastructure-as-code
templates, documentation bundles, or configuration files that need packaging,
versioning, or transformation.

---

### 🔧 What Constitutes a Build?

A typical build process may include:

- 🔄 **Compiling code**: e.g., `.java → .class`, `.ts → .js`
- 📦 **Bundling dependencies**: e.g., NPM modules, Maven packages
- 📦 **Packaging artifacts**: e.g., JAR, Docker image, zip file
- 🏷️ **Versioning**: tagging or stamping artifacts
- 🧪 **Static analysis** *(pre-build or during build)*
- 🧬 **Configuration templating**: injecting environment-specific variables

---

### 🧪 Build Examples and Edge Cases

| **Type** | **Is it a Build?** | **Example** | **Notes** |
|-------------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------|
| Java code to JAR | ✅ Yes | Compile `.java` to `.jar` | Traditional code compilation |
| Markdown to HTML | ✅ Yes | Static site generation (e.g., Hugo) | Transforms content into deployable form |
| CSS/JS minification | ✅ Yes | Bundle & minify assets | Common in front-end workflows |
| Copying static files | ❌ Not typically | File copying without transformation | Often part of build but not a build by itself |
| Helm template to Kubernetes | ✅ Yes | `helm template` to render manifests | Generates deployable infra config |
| Helm chart packaging | ✅ Yes | `helm package` to create `.tgz` chart | Versioned artifact used in CI/CD pipelines |
| Helm deployment | ❌ No | `helm install` or `upgrade` | Deployment, not artifact creation |

---

### 🧰 Tool-Specific Considerations

| **Tool** | **Definition of Build** |
|------------------|-------------------------------------------------------------------|
| Jenkins | A "build" typically refers to a job run (can be compile, test, etc.) |
| GitHub Actions | No strict definition — "build" is defined by your workflow steps |
| GitLab CI/CD | Often treated as a named stage (e.g., `build`, `test`, `deploy`) |
| Spinnaker | Uses "bake" or "artifact" stages, and may trigger builds externally |

---

## 🧪 Test

A **test** is the automated process of executing code, configuration, or system
components to **verify correctness, quality, and adherence to specified
requirements**. It provides feedback on whether a system behaves as expected
under various conditions.

---

### 🔬 What Are “Test Assets”?

Test assets encompass any components, data, or environments specifically
designed or required to perform testing. These include:

- **Test Cases**: Specific inputs, execution steps, and expected outputs or behaviors.
- **Test Suites**: Collections of related test cases, often grouped by functionality or type.
- **Test Data**: Data used as input for test cases (e.g., mock data, sanitized production data).
- **Test Environments**: Specific configurations of hardware, software, and network settings where tests are executed.
- **Test Frameworks**: Libraries or tools that facilitate writing, executing, and reporting tests (e.g., JUnit, Pytest, Selenium, Jest).
- **Test Reports**: Summaries of test execution, including pass/fail status, errors, and performance metrics.

---

### 📊 What Constitutes a Test?

A typical automated test process may include:

- 🚀 **Execution**: Running one or more test cases against the system under test.
- 🔍 **Assertion**: Comparing actual outputs or behaviors against expected outcomes.
- ✅ **Validation**: Determining whether the test passed or failed based on assertions.
- 📝 **Reporting**: Generating logs, metrics, and reports of test results.
- ⚙️ **Setup/Teardown**: Preparing the test environment before execution and cleaning up resources afterward.
- 📈 **Coverage Analysis**: Measuring the extent to which the code or system has been exercised by tests.

---

### 🧪 Test Examples and Edge Cases

| **Type** | **Is it a Test?** | **Example** | **Notes** |
|------------------------------|-------------------|-----------------------------------------------------|-------------------------------------------------------------------|
| Unit Test | ✅ Yes | JUnit tests for a Java class | Verifies individual components in isolation |
| Integration Test | ✅ Yes | API tests verifying service interaction | Checks communication and data flow between modules |
| Functional/Acceptance Test | ✅ Yes | Selenium UI tests for a web application | Validates end-to-end user flows against requirements |
| Performance Test | ✅ Yes | JMeter load test on an API endpoint | Assesses system responsiveness and stability under load |
| Security Scan (SAST/DAST) | ✅ Yes | SonarQube static analysis, OWASP ZAP dynamic scan | Identifies vulnerabilities (often automated in CI/CD) |
| Contract Test | ✅ Yes | Pact tests between consumer and provider APIs | Ensures API compatibility between services |
| Accessibility Test | ✅ Yes | Automated WCAG compliance checks (e.g., Axe) | Verifies usability for people with disabilities |
| Manual Exploratory Testing | ❌ No | Human tester exploring application functionality | Not an automated process, thus outside CDEvents scope |
| Code Linting/Formatting | ❌ No | `prettier --check`, `gofmt` | Focuses on code style and consistency, not functional correctness |
| Dependency Vulnerability Scan| ❌ No | `npm audit`, Snyk scan | Scans for known vulnerabilities in dependencies, not functional test of *your* code |

---

### 🧰 Tool-Specific Considerations

| **Tool** | **Definition of Test** |
|------------------|----------------------------------------------------------------|
| Jenkins | Defined by pipeline steps that execute test commands (e.g., `mvn test`) |
| GitHub Actions | Typically a job or step that runs test commands or frameworks |
| GitLab CI/CD | Often a dedicated job stage (e.g., `test` stage) with test execution commands |
| Azure DevOps | "Test Plans" or "Test Pipelines" that run automated tests and publish results |
| SonarQube | Primarily for static analysis and code quality, but often integrated with test results for coverage |
| Jest/JUnit/Pytest| Frameworks for writing and executing tests within codebases |
| Selenium/Cypress | Frameworks for automated browser-based functional testing |

---

## 💾 Store

**Storing** is the automated process of persistently saving, managing, and
making accessible any **artifact, data, or metadata** generated or consumed
during the SDLC. It ensures that necessary components and information are
retrievable for future use, auditing, or deployment.

---

### 📦 What Are “Stored Assets”?

Stored assets encompass any durable output or input that is preserved across
the SDLC. These include:

- **Build Artifacts**: Executables, container images, packages, libraries (e.g., JARs, WARs, Docker images, npm packages).
- **Source Code**: The versioned codebase managed in a Version Control System (VCS).
- **Configuration**: Environment-specific settings, deployment manifests, or infrastructure-as-code definitions.
- **Test Results**: Reports, logs, and metrics from test executions.
- **Logs**: Runtime logs from applications or infrastructure.
- **Metrics**: Performance, usage, or health data collected over time.
- **Documentation**: Generated or manually created documentation.
- **Snapshots/Backups**: Point-in-time copies of databases or systems.

---

### 🗄️ What Constitutes Storing?

A typical automated storing process may include:

- ⬆️ **Publishing/Uploading**: Transferring an asset to a designated repository or storage location.
- 🏷️ **Tagging/Versioning**: Assigning unique identifiers or metadata to stored assets for traceability.
- 📦 **Indexing**: Cataloging assets within a repository for efficient searching and retrieval.
- 🔐 **Access Control**: Applying permissions to regulate who can access or modify stored assets.
- 🧹 **Retention/Cleanup**: Managing the lifecycle of stored assets, including deletion policies.
- 🔄 **Replication**: Copying assets to multiple locations for redundancy or distribution.
- 🔗 **Linking**: Establishing relationships between stored assets and other SDLC events (e.g., linking an artifact to the build that produced it).

---

### 💾 Store Examples and Edge Cases

| **Type** | **Is it Storing?** | **Example** | **Notes** |
|------------------------------------|--------------------|-----------------------------------------------------|-------------------------------------------------------------------|
| Push Docker Image to Registry | ✅ Yes | `docker push myrepo/myapp:1.0` | Persistently saves a container image for distribution |
| Upload JAR to Maven Repository | ✅ Yes | `mvn deploy` to Artifactory | Stores a compiled library for dependency management |
| Commit Code to Git Repository | ✅ Yes | `git push origin main` | Persists source code and its history |
| Save Test Results to Database | ✅ Yes | Storing JUnit XML reports in a test management system | Preserves test outcomes for analysis and auditing |
| Upload Build Logs to Object Storage| ✅ Yes | Uploading CI/CD pipeline logs to S3 | Archiving diagnostic information |
| Deploying Application to Server | ❌ No | `kubectl apply -f deployment.yaml` | This is deployment/execution, not just persistent storage of an artifact |
| Caching Build Dependencies | ❌ No | Local Maven `.m2` repository cache | Temporary storage for performance, not persistent distribution |
| Downloading a Dependency | ❌ No | `npm install` | Retrieval from storage, not the act of storing |
| Writing a Log File to Local Disk | ❌ No | `logger.info("message")` to a local file | Local/temporary persistence; "storing" implies a managed, accessible repository |

---

### 🧰 Tool-Specific Considerations

| **Tool** | **Definition of Store** |
|------------------|------------------------------------------------------------------|
| Artifactory/Nexus| Dedicated artifact repositories for various package types (Maven, npm, Docker, etc.) |
| Docker Registry | Stores and manages Docker container images |
| Git/GitHub/GitLab| Version Control Systems that store source code and its history |
| Amazon S3/Azure Blob Storage/GCS | Object storage services used for archiving logs, backups, or raw data |
| Kubernetes | Can store configuration via ConfigMaps/Secrets, but not typically "artifacts" |
| Helm Chart Museum| Stores and serves Helm charts |
| Test Management Systems (e.g., TestRail) | Stores test cases, test runs, and results for manual and automated tests |