diff --git a/content/en/docs/primer/definitions.md b/content/en/docs/primer/definitions.md new file mode 100644 index 0000000..879563f --- /dev/null +++ b/content/en/docs/primer/definitions.md @@ -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 | +