← Back to catalogue
Published

Software Change / Pull Request

vr.wm-sft-013 · wm-sft-013-software-change-pull-request

Describe one persistent proposed software change through revisions, assessment and integration outcomes.

World Models Information and virtual systems INF.SFT.CHG
Bundle → Layer → Finding → QuestionsClassifiersWhat it isWhy it existsDistinguishing featuresWhat robots and AI may and may not doMoral aspectsOwnersLinks to other meta-modelsIdentity and identifiersDirect propertiesRecognitionCapabilities and actionsHazards and failure modesStandards and interfacesContext of useSources

Bundle → Layer → Finding → Questions Filled

3 bundles · 4 layers · 5 findings · 10 questions

Proposed change What is proposed and why.

Diff and intent

The changes, their target and their motivation.

Source and target

The source branch, the target branch and the commits included.

  1. Which branch or fork does the change come from, and which branch does it target?
  2. Which commits and files does it change?

Motivation

The issue, defect or requirement the change addresses.

  1. Which issue, defect or requirement does the change address?
  2. Who authored the change, and was any of it generated by a tool?
Review and checks How the change was verified before merge.

Review

Human review and approvals.

Approvals

Reviewers, their verdicts and required approvals.

  1. Who reviewed the change, and did the required reviewers approve it?
  2. Were review comments resolved before merge?

Automated checks

Tests, scans and policy checks on the change.

Check results

Results of tests, builds and security scans.

  1. Which tests and scans ran on the final revision, and did they pass?
  2. Were any failing checks overridden, and by whom?
Outcome What happened to the change.

Merge or closure

The merge, rejection or abandonment of the change.

Final state

Merged, closed or open, with the resulting commit.

  1. Was the change merged, closed or left open?
  2. Which merge commit resulted, and was it later reverted?

Classifiers Filled

Family
World Models
Category
Information and virtual systems
Entry kind
entity
Navigation path
NAV.INF.SFT.CHG
Domain
INF.SFT.CHG
Industry
Cross-industry
Tags
softwarechangepullrequestinf.sft.chg

What it is Filled

A software change or pull request is a proposed set of changes to a source repository, presented for review and automated checks and then merged, revised or closed. Single commits outside a review, the build or release that later ships the change, and the defect or requirement that motivated it are separate subjects.

In scope

  • Master identity, accountable roles, intent and typed links
  • Revision-specific diff, review, check and policy evidence
  • Observed readiness, lifecycle outcomes, lineage and controlled record views

Out of scope

  • Repository administration, commit storage and branch mutation owned by WM-SFT-005
  • Defect and requirement lifecycle, vulnerability exploitation, CI execution, deployment and release management
  • Enforcing branch policy, granting merge authority, performing merges/reverts, issuing compliance certification
  • Unreviewed direct commits without a proposal record; organization-wide change control

Why it exists Filled

Describe one persistent proposed software change through revisions, assessment and integration outcomes.

Distinguishing features Filled

  • A unit of proposed change with a review lifecycle, not a plain commit in history.
  • Belongs to a source repository and targets a branch, while builds and releases come later.
  • Carries review and check evidence that supports change control and audit.
  • Distinct from a change request in operations, which governs changes to running services.

What robots and AI may and may not do Filled

Must not

  • Merge a change without the approvals and passing checks the repository requires.
  • Approve its own change where independent review is required.
  • Bypass branch protection or force-push over others' work.
  • Commit secrets, credentials or personal data in a change.
  • Hide that a change was generated or modified by an automated agent where the project requires disclosure.

Only with a human decision

  • Approving changes to protected branches.
  • Overriding a failing required check.
  • Merging changes that affect security, licensing or production configuration.

May

  • Open a pull request with a clear description of the change and its motivation.
  • Run and report automated checks on a change.
  • Review changes and comment on defects, risks and style.
  • Summarize a change for reviewers.

Moral aspects Filled

  • Review is a key defence against defects and supply-chain attacks that reach many users.
  • Contributor credit and licence terms must be respected for every change.
  • Review comments affect people's work and should address the code, not the person.

Who is affected

  • Contributors and reviewers
  • Maintainers of the repository
  • Users of the software
  • Downstream projects that depend on it

Owners Filled

Steward

The maintainers of the target repository, who decide whether a change is merged.

Roles

Contributor
Supply intent and revision references; authorship does not confer integration authority
Reviewer
Assess identified material within delegated scope and disclose policy-required conflicts
Repository maintainer
Own applicable integration policy and authoritative outcome decisions
Check producer
Identify evaluated inputs, execution attempt and result provenance
Record steward
Control local mappings, access, correction and disposition
Audit reader
Inspect permitted evidence and report gaps without silently changing verdicts

Master systems

  • Source code hosting platform
  • Version control system
  • Continuous integration system

Links to other meta-models Filled

references

  • WM-SFT-005 - Repository context implements the inverse navigation of the incoming candidate CONTAINS edge without owning repository administration. Binding version remains to be pinned.
  • WM-SFT-014 - Optional reciprocal traceability for the incoming defect REFERENCE edge; defect status and proof of resolution stay at its master.
  • External review, check and policy masters - Bind evidence and applicable policy using versioned native identifiers; do not duplicate execution or enforcement.
  • External build and release records - Link outcome evidence and attestation subjects; no mandatory build or delivery record for every proposal.

aligned

  • PROV-O - Conceptual assertion, revision, activity and actor vocabulary mapping, without ontology conformance claim.
  • SLSA provenance/v1 - Interpret referenced build attestations under a pinned verifier profile; no SLSA level claim for a proposal.

neighbor

  • WM-SFT-005 Source Repository - Honor incoming candidate CONTAINS: each proposal references its repository context. Repository identity, permissions and history remain mastered there; containment is not entity-kind inheritance.
  • WM-SFT-014 Defect - Honor incoming candidate REFERENCE: a defect may reference a resolving proposal. Optional reciprocal traceability here does not close the defect or prove resolution.
  • Commit and patch-set records - A persistent proposal can acquire multiple revisions and many input or resulting commits. Hash identity never replaces the scoped proposal key.
  • Build, release, deployment and attestation records - Link their independently mastered evidence. Merge and check success do not prove release, deployment or artifact provenance compliance.
  • Operations change authorization - Software integration proposal records evidence about code change; operational authorization remains separate even when references connect them.

parent

  • WM-SFT-005

What else AI and robots need to interact with it Filled

Identity and identifiers required Filled

  • Identified by the repository plus the pull or merge request number assigned by the hosting platform.
  • Each revision is identified by its head commit hash.

Direct properties not applicable Not applicable

Not applicable

The subject is an information or institutional record, not a physical object, so it has no physical properties to measure.

Recognition optional Filled

  • Recognized by a source branch, a target branch, a diff, a description and a review state.
  • Often confused with a commit, a branch or the issue it addresses.

Capabilities and actions required Filled

  • Can be opened, updated, reviewed, approved, merged, reverted or closed.
  • Can trigger automated builds, tests and scans.
  • Can link to issues and close them when merged.

Hazards and failure modes required Filled

  • Malicious or vulnerable code entering the main branch.
  • Leaked secrets in diffs or history.
  • Broken builds and outages from untested merges.

Standards and interfaces required Filled

  • Git version control and its patch formats.
  • Hosting platform APIs for pull or merge requests and reviews.
  • SLSA framework for build provenance of merged changes.

Context of use required Filled

  • Used in open source and in-house software development.
  • Regulated industries use review records as evidence of change control.

Sources Filled

  1. Pull requests - GitHub
  2. About protected branches - GitHub
  3. Merge requests API - GitLab
  4. Changes - Gerrit project
  5. git-diff documentation - Git project
  6. Secure Software Development Framework Version 1.1 - National Institute of Standards and Technology
  7. PROV-O: The PROV Ontology - World Wide Web Consortium
  8. SLSA Provenance - SLSA project
  9. Supply-chain Levels for Software Artifacts (SLSA), Open Source Security Foundation
  10. ISO/IEC/IEEE 12207 Systems and software engineering - Software life cycle processes, ISO/IEC/IEEE

Open questions

  • Run direct source retrieval and review current documentation against version-pinned target deployments; retain the frozen audit evidence and reassess any changed claims.
  • Implement nested schemas and profile-specific mappings with fixtures for rewritten revisions, moving targets, stale checks, skipped results, partial diffs, unknown outcomes and restricted artifacts.
  • Obtain independent second-provider review and qualified owner review of retention, licensing and regulated adoption; investigate mail-based and non-Git proposal profiles separately.
  • Exhaustive platform state machines, mail-based patch workflows and non-Git implementations
  • Nested data schemas, pinned neighbor versions, verified API bindings and executable fixtures
  • Current deployment/version certification and independent second-provider review
  • Jurisdiction-specific retention, licensing and regulated change-control applicability

Machine files

Card as JSON Specification AGENTS.md Source Card backlog vercy.card/1

Provenance

world-models research · reviewable-draft

Built from: models/wm-sft-013-software-change-pull-request/spec.yaml, ver-cy/world-models/card-supplements/wm-sft-013-software-change-pull-request.json