# Software Configuration Management Plan: [Project or product name]

> Complete Software Configuration Management Plan (SCMP). The structure
> follows the configuration management plan content described in IEEE
> 828-2012: introduction, SCM management, configuration identification,
> configuration control, status accounting, audits and reviews, interface
> control, release management, tools and records. Replace every
> `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- Configuration management answers four questions at any moment: what are
  the parts, what version of each is in a given release, who changed what and
  why, and does the release match its records.
- Start with configuration identification (section 3). Everything else
  (control, accounting, audits) works on the items you name there.
- Describe the process the team actually follows in the repository and
  pipeline. An SCMP that contradicts the branch protection settings is worse than none.
- Keep naming conventions concrete, with real examples, so tooling can enforce them.
-->

## Document control

<!-- Guidance: Identify the plan. The SCMP is itself a configuration item; put it under the control it describes. -->

| Field | Value |
|---|---|
| Document ID | [SCMP-PROJECT-001] |
| Project / product | [Project name] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@configuration-manager] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Repository location of this plan | [`docs/scm-plan.md` in repository X] |
| Related documents | [Project management plan], [SQA plan], [Release plan], [Change management procedure] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Configuration manager | [@name] | [Approved / Rejected / Approved with comments] | YYYY-MM-DD |
| Project manager | [@name] | [Decision] | YYYY-MM-DD |
| Engineering lead | [@name] | [Decision] | YYYY-MM-DD |
| SQA lead | [@name] | [Decision] | YYYY-MM-DD |

## Revision history

<!-- Guidance: One row per approved version. -->

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | Initial draft |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Switched from Git Flow to trunk-based development with release branches |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved by the change control board |

## Contents

<!-- Guidance: Keep in sync with headings. -->

1. [Introduction](#1-introduction)
2. [SCM management](#2-scm-management)
3. [Configuration identification](#3-configuration-identification)
4. [Configuration control](#4-configuration-control)
5. [Configuration status accounting](#5-configuration-status-accounting)
6. [Configuration audits and reviews](#6-configuration-audits-and-reviews)
7. [Interface control](#7-interface-control)
8. [Release management and delivery](#8-release-management-and-delivery)
9. [Supplier and third-party item control](#9-supplier-and-third-party-item-control)
10. [SCM tools and infrastructure](#10-scm-tools-and-infrastructure)
11. [SCM schedule and resources](#11-scm-schedule-and-resources)
12. [Records and plan maintenance](#12-records-and-plan-maintenance)
13. [Glossary and references](#13-glossary-and-references)

## 1. Introduction

<!-- Guidance: Describe the system under configuration control and the scope of the plan. Readers include new engineers, auditors and the customer. -->

### 1.1 Purpose

This plan defines how [organisation] identifies, controls, records and
audits the configuration of [product name] from project start to [end of
support], so that every delivered release can be reproduced and every
change can be traced to an approved request.

### 1.2 Scope

| Aspect | Covered |
|---|---|
| Software items | [Web application, Orders API, mobile app, infrastructure as code, database schema] |
| Documentation | [Requirements, architecture, test documentation, user guides, this plan] |
| Environments | [Build, test, staging and production configuration] |
| Life-cycle span | Development, release, maintenance until [end-of-support date] |
| Organisations | [Internal teams], [Supplier X], [Customer acceptance team] |

### 1.3 Key terms

| Term | Meaning in this plan |
|---|---|
| Configuration item (CI) | A work product placed under configuration control and managed as one unit |
| Baseline | An approved, frozen set of CI versions that serves as the basis for further work |
| Change control board (CCB) | The group that approves or rejects changes to baselined items |
| Release | A baseline packaged and delivered to a user or environment |

## 2. SCM management

<!-- Guidance: Who does SCM, with what authority, and under which policies. Make the CCB composition and quorum explicit. -->

### 2.1 Organisation

| Role | Responsibilities | Authority |
|---|---|---|
| Configuration manager | Owns this plan, maintains CI register, runs status accounting, leads audits | Can block a release that fails audit |
| Change control board | Approves changes to baselines; prioritises change requests | Approve, reject, defer changes |
| Release manager | Builds, signs and delivers releases | Can stop a deployment |
| Developers | Work in branches per section 3.4; link commits to change requests | Merge after review |
| SQA lead | Verifies conformance to this plan | Raises findings |
| Repository administrators | Maintain access rights and branch protection | Change repository settings via change request |

### 2.2 Change control board

| Item | Value |
|---|---|
| Chair | [Product owner or programme manager] |
| Members | [Engineering lead, test manager, operations lead, configuration manager, security lead] |
| Quorum | Chair plus three members including engineering and test |
| Meeting cadence | [Weekly; ad hoc for emergency changes] |
| Decisions recorded in | [Change request ticket and CCB minutes] |

### 2.3 Policies

- Every change to a baselined CI is linked to an approved change request or defect ID.
- No direct commits to protected branches; all changes arrive through reviewed pull requests.
- Every release is built by the CI pipeline from a tagged commit; local builds are never shipped.
- Build inputs (dependencies, base images, tools) are pinned and recorded.
- Access to production configuration follows least privilege and is reviewed [quarterly].

## 3. Configuration identification

<!-- Guidance: List the configuration items, how they are named and versioned, and which baselines are established when. If you cannot point to a CI in the repository, it is not identified. -->

### 3.1 Configuration items

| CI ID | Name | Type | Location | Owner | Baseline in |
|---|---|---|---|---|---|
| CI-SRS | Software requirements specification | Document | `docs/requirements/srs.md` | [@analyst] | Requirements baseline |
| CI-ARCH | Architecture description | Document | `docs/architecture/` | [@architect] | Design baseline |
| CI-WEB | Web application source | Source code | `apps/web` | [@web-lead] | Product baseline |
| CI-API | Orders API source | Source code | `services/orders` | [@api-lead] | Product baseline |
| CI-DB | Database schema and migrations | Source code | `services/orders/migrations` | [@api-lead] | Product baseline |
| CI-IAC | Infrastructure as code | Configuration | `infra/` | [@platform-lead] | Product baseline |
| CI-TEST | Automated test suites | Source code | `tests/` | [@test-lead] | Product baseline |
| CI-DEPS | Dependency lockfiles and SBOM | Configuration | `pnpm-lock.yaml`, `sbom.json` | [@configuration-manager] | Product baseline |
| [CI-xxx] | [Name] | [Type] | [Location] | [@owner] | [Baseline] |

### 3.2 Naming and versioning conventions

| Object | Convention | Example |
|---|---|---|
| Release version | Semantic versioning `MAJOR.MINOR.PATCH` | `4.2.1` |
| Pre-release | `MAJOR.MINOR.PATCH-rc.N` | `4.2.0-rc.3` |
| Git tag | `v` + version | `v4.2.1` |
| Release branch | `release/MAJOR.MINOR` | `release/4.2` |
| Feature branch | `feat/<ticket>-<short-name>` | `feat/ORD-812-split-shipping` |
| Fix branch | `fix/<ticket>-<short-name>` | `fix/ORD-901-tax-rounding` |
| Container image | `<registry>/<service>:<version>` plus digest | `registry.example/orders-api:4.2.1` |
| Document version | `MAJOR.MINOR` in document control table | `1.3` |
| Database migration | `NNNN_<description>.sql`, never edited after merge | `0042_add_split_shipping.sql` |

### 3.3 Baselines

| Baseline | Established when | Contents | Approved by |
|---|---|---|---|
| Requirements baseline | Requirements review passed | CI-SRS, acceptance criteria | CCB |
| Design baseline | Design review passed | CI-ARCH, ADRs, interface specifications | CCB |
| Product baseline (per release) | Release candidate passes test completion criteria | All code, configuration, tests, SBOM at a tagged commit | CCB and release manager |
| Operational baseline | Release deployed to production | Product baseline plus production configuration values | Operations lead |

### 3.4 Branching model

The project uses trunk-based development with short-lived feature
branches and a release branch per minor version for stabilisation and
patches.

```mermaid
flowchart LR
  F1["feat/ORD-812"] -- "pull request" --> M["main (trunk)"]
  F2["fix/ORD-901"] -- "pull request" --> M
  M -- "branch at code freeze" --> R["release/4.2"]
  R -- "tag" --> T1["v4.2.0"]
  H["fix on release/4.2"] -- "pull request" --> R
  R -- "tag" --> T2["v4.2.1"]
  R -- "cherry-pick fix back" --> M
```

| Branch | Protection | Who can merge | Lifetime |
|---|---|---|---|
| `main` | Review by one code owner, all checks green, linear history | Developers after approval | Permanent |
| `release/*` | Review by two, CCB-approved change request linked | Release manager | Until end of support of that minor version |
| `feat/*`, `fix/*` | None | Author | Deleted after merge (target under 3 days) |

## 4. Configuration control

<!-- Guidance: Define how a change to a baselined item is requested, evaluated, approved, implemented and verified. Distinguish routine, normal and emergency changes. -->

### 4.1 Change classes

| Class | Examples | Approval | Lead time |
|---|---|---|---|
| Routine (pre-approved) | Dependency patch within policy, copy fix | Code review only | None |
| Normal | New feature, schema change, configuration change in production | CCB | Next CCB meeting |
| Emergency | Fix for severity-1 incident | CCB chair plus one member, reviewed at next CCB | Hours |

### 4.2 Change request content

Each change request (CR) records: ID, title, requester, date, affected
CIs, reason, description, impact analysis (scope, schedule, cost, risk,
interfaces, security), priority, CCB decision and date, implementing
branch or pull request, verification evidence, and closure date.

| CR ID | Title | Affected CIs | Impact | Decision | Date |
|---|---|---|---|---|---|
| CR-0147 | *Example:* Support split shipping for multi-warehouse orders | CI-API, CI-DB, CI-WEB, CI-SRS | 3 weeks; schema migration; new interface with warehouse system | Approved for 4.3 | YYYY-MM-DD |
| CR-0151 | *Example:* Upgrade runtime to next LTS | CI-API, CI-IAC, CI-DEPS | 4 days; regression test full suite | Deferred to 4.4 | YYYY-MM-DD |
| [CR-nnnn] | [Title] | [CIs] | [Impact] | [Decision] | YYYY-MM-DD |

### 4.3 Change control flow

The flow below applies to normal changes. Routine changes skip the CCB
step; emergency changes are approved by the chair and ratified afterwards.

```mermaid
flowchart TD
  A["Change request raised"] --> B["Impact analysis by CI owners"]
  B --> C{"CCB decision"}
  C -- "approved" --> D["Implement in branch, link CR"]
  C -- "rejected" --> X["Close CR with reason"]
  C -- "deferred" --> Q["Backlog with review date"]
  D --> E["Review and CI checks"]
  E --> F["Merge to target branch"]
  F --> G["Verify in test environment"]
  G --> H["Update status accounting, close CR"]
```

### 4.4 Deviations and waivers

A request to release a CI that does not meet its requirements is handled
as a deviation or waiver with CCB approval, an expiry date and a linked
corrective change request.

## 5. Configuration status accounting

<!-- Guidance: Status accounting is the record of what exists and what changed. Define the reports, who receives them and where the data comes from. -->

| Report | Content | Source | Frequency | Audience |
|---|---|---|---|---|
| CI register | Every CI with current version and owner | Repository, this plan | Continuous | Everyone |
| Change request status | Open, approved, implemented, closed CRs with ageing | Issue tracker | Weekly | CCB |
| Baseline content list | CI versions in each baseline, commit SHA, image digests | Release pipeline | Per baseline | CCB, auditors |
| Release notes | Changes, fixes, known issues per release | CRs and pull requests | Per release | Users, support |
| Deployed version report | Version running in each environment | Deployment tool | Continuous | Operations |

Status data is generated from tools wherever possible; manual registers
are reconciled against the repository [monthly].

## 6. Configuration audits and reviews

<!-- Guidance: Audits confirm that a baseline is what it claims to be. The functional audit checks behaviour against requirements; the physical audit checks contents against records. -->

| Audit | Purpose | When | Evidence examined | Performed by |
|---|---|---|---|---|
| Functional configuration audit (FCA) | Confirm the CI performs as specified | Before product baseline | Test completion report, traceability matrix, open defects | Configuration manager, test manager, SQA |
| Physical configuration audit (PCA) | Confirm the release contents match the baseline records and documentation | Before delivery | Tag, build provenance, SBOM, image digests, release notes, installation guide | Configuration manager, SQA |
| In-process review | Check that this plan is followed day to day | [Monthly] | Sample of merged pull requests and CRs | SQA |

### 6.1 Audit checklist (PCA excerpt)

- [ ] Release tag points to a commit on the release branch.
- [ ] Build was produced by the CI pipeline; provenance attestation present.
- [ ] Image digests in the deployment manifest match the registry.
- [ ] SBOM generated from the same build and archived.
- [ ] Every change since the previous release links to a CR or defect.
- [ ] Release notes and installation guide match the delivered version.

Audit findings follow the corrective action process in the SQA plan.

## 7. Interface control

<!-- Guidance: List interfaces with items outside this plan's control and how changes on either side are coordinated. Unmanaged interfaces cause most integration failures. -->

| Interface ID | Between | Specification | Owner of specification | Change coordination |
|---|---|---|---|---|
| IF-01 | Orders API and web application | OpenAPI file `services/orders/openapi.yaml` | API lead | Contract tests; breaking changes need CR and version bump |
| IF-02 | Orders API and warehouse system (external) | Interface control document ICD-WH-003 | [Partner] | Joint interface board; 30 days notice for changes |
| IF-03 | Platform and payment provider | Provider API version [2025-xx] | Provider | Pin API version; review provider changelog monthly |
| [IF-nn] | [Parties] | [Specification] | [Owner] | [Process] |

## 8. Release management and delivery

<!-- Guidance: Describe how a baseline becomes a release, how it is built, signed, stored, delivered and, if needed, rolled back. -->

### 8.1 Release types

| Type | Version change | Branch | Approval |
|---|---|---|---|
| Major | `MAJOR` | `release/N.0` | CCB, product owner |
| Minor | `MINOR` | `release/N.M` | CCB |
| Patch | `PATCH` | Existing `release/N.M` | Release manager, CCB informed |
| Emergency hotfix | `PATCH` | Existing `release/N.M` | CCB chair |

### 8.2 Build and packaging

- Builds run in the CI pipeline from a clean checkout of the tag.
- Artifacts are signed [with Sigstore / GPG key ID] and stored in [artifact registry] with immutable tags.
- Build provenance and SBOM are attached to each artifact.
- Builds are reproducible: rebuilding the same tag produces artifacts with the same content hashes, or differences are documented.

### 8.3 Delivery and deployment

| Step | Action | Evidence |
|---|---|---|
| 1 | Deploy signed artifact to staging; run smoke tests | Pipeline log |
| 2 | CCB go decision recorded | CR or minutes |
| 3 | Deploy to production [canary 10% then 100%] | Deployment record |
| 4 | Update deployed version report and release notes | Status accounting |
| 5 | Archive release package and audit records | Records store |

### 8.4 Rollback

Every release keeps the previous production artifact available. Rollback
is a redeploy of the previous tag; database migrations are written to be
backward compatible for one release so rollback needs no schema reversal.

## 9. Supplier and third-party item control

<!-- Guidance: Third-party code and supplier deliveries are CIs too. Say how they are received, checked and versioned. -->

| Item | Source | Control |
|---|---|---|
| Open-source dependencies | Package registries | Pinned in lockfiles; new packages approved per dependency policy; vulnerability scan in CI |
| Base container images | [Registry] | Pinned by digest; rebuilt monthly |
| Supplier deliveries | [Supplier A] | Delivered to a dedicated repository; inspected and tagged on receipt; merged by CR |

## 10. SCM tools and infrastructure

<!-- Guidance: Name each tool, its role and how it is backed up and secured. -->

| Purpose | Tool | Backup and security |
|---|---|---|
| Version control | [Git hosting service] | Daily mirror to [location]; SSO and MFA required |
| Change requests and defects | [Issue tracker] | Vendor backup; export weekly |
| CI and release pipeline | [CI service] | Pipeline as code in repository |
| Artifact and image registry | [Registry] | Immutable tags; replication to second region |
| Infrastructure state | [IaC tool and state backend] | Encrypted, versioned state storage |

## 11. SCM schedule and resources

<!-- Guidance: List when SCM activities occur relative to the project schedule and the effort they need. -->

| Activity | Timing | Effort |
|---|---|---|
| Set up repositories, branch protection, pipelines | Project week 1-2 | [5 person-days] |
| Establish requirements and design baselines | At review milestones | [1 day each] |
| CCB meetings | Weekly | [1 hour per member] |
| FCA and PCA | Before each minor or major release | [2 days] |
| Status accounting reconciliation | Monthly | [0.5 day] |

## 12. Records and plan maintenance

<!-- Guidance: List SCM records and retention, and how this plan itself is kept current. -->

| Record | Location | Retention |
|---|---|---|
| Change requests and CCB minutes | [Issue tracker, wiki] | [Product life + 3 years] |
| Baseline content lists and SBOMs | [Records store] | [Product life + 3 years] |
| Audit reports | [Records store] | [Product life + 3 years] |
| Release packages | [Artifact registry] | [Until end of support + 1 year] |

This plan is reviewed [at each major release and at least annually]. Changes
to it are made by pull request and approved by the CCB.

## 13. Glossary and references

<!-- Guidance: Define any further terms and list referenced documents. -->

| Term | Meaning |
|---|---|
| FCA | Functional configuration audit |
| PCA | Physical configuration audit |
| SBOM | Software bill of materials: list of components in a build |
| Provenance | Verifiable record of how and from what an artifact was built |

References: [Project management plan], [SQA plan], [Release plan],
[Dependency policy], IEEE 828-2012, *IEEE Standard for Configuration
Management in Systems and Software Engineering*.

## Standard and licence note

Structure aligned with IEEE 828-2012, *IEEE Standard for Configuration
Management in Systems and Software Engineering*, configuration management
plan content. This template is original text written for this collection
and reproduces no text from the standard; obtain the standard from IEEE
for its normative requirements. Template licence: MIT.