151 lines
5.1 KiB
Markdown
151 lines
5.1 KiB
Markdown
# INTENT
|
|
|
|
> This file captures **why this repository exists**,
|
|
> the **direction it is moving toward**, and
|
|
> the **kind of system it is meant to become**.
|
|
> It is intentionally **aspirational and stable**, not a description of current implementation.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
**The developer enablement layer - turning Railiance platform capabilities into paved paths for building, testing, packaging, and promoting workloads.**
|
|
|
|
---
|
|
|
|
## Why This Exists
|
|
|
|
A healthy platform does not automatically make delivery easy.
|
|
Developers and operators still need repeatable ways to build workloads, test
|
|
them, package them, route them through review, and hand them to application
|
|
release surfaces without inventing those paths from scratch each time.
|
|
|
|
Without a disciplined enablement layer:
|
|
|
|
* every workload invents a different pipeline,
|
|
* build and deployment templates drift,
|
|
* platform capabilities are hard to consume correctly,
|
|
* and application releases depend on undocumented operator memory.
|
|
|
|
This layer exists to provide **paved delivery paths**: shared automation,
|
|
templates, SDKs, build conventions, and self-service workflows that let
|
|
Railiance evolve faster without dissolving its layer boundaries.
|
|
|
|
---
|
|
|
|
## The Mission
|
|
|
|
> *Where we are going.*
|
|
|
|
To become the **canonical home for developer and delivery enablement** -
|
|
CI/CD pipelines, GitOps workflows, workload templates, SDKs, buildpacks,
|
|
developer portal surfaces, and promotion conventions that help source repos
|
|
move safely toward S5 application releases while consuming forge-provided
|
|
runners, registries, and artifact evidence.
|
|
|
|
This means:
|
|
|
|
* Common delivery paths are **automated and reusable**
|
|
* Build and deployment templates encode **Railiance platform expectations**
|
|
* Developers get fast feedback through **standard checks and pipelines**
|
|
* S5 can consume release artifacts through **clear handoff contracts**
|
|
* Forge runtime and runner substrate remain owned by **railiance-forge**
|
|
* Enablement improves delivery without taking ownership of app runtime
|
|
operation
|
|
|
|
---
|
|
|
|
## Core Principles
|
|
|
|
### 1. Paved Paths, Not One-Off Pipelines
|
|
|
|
The default way to build, test, package, and promote a workload should be
|
|
shared, documented, and easy to reuse.
|
|
|
|
### 2. Enablement, Not Applications
|
|
|
|
This layer helps applications reach production; it does not own their source
|
|
code, runtime configuration, or user-facing operations.
|
|
|
|
### 3. Platform-Aware Templates
|
|
|
|
Templates, SDKs, and buildpacks should encode the contracts exposed by S1-S3 so
|
|
consumers do not need to rediscover platform assumptions.
|
|
|
|
### 4. Clear Handoff to S5
|
|
|
|
CI/CD and promotion flows should produce artifacts, metadata, and evidence that
|
|
the application layer can deploy and verify without guessing.
|
|
|
|
### 5. Clear Handoff to Forge
|
|
|
|
Reusable workflows should state the forge capabilities they require: repository
|
|
events, runner labels, package credentials, registry endpoints, and artifact
|
|
evidence. This layer defines the reusable workflow shape; `railiance-forge`
|
|
owns the runtime and credentials behind it.
|
|
|
|
### 6. Fast Feedback
|
|
|
|
Developers should learn about broken builds, missing declarations, incompatible
|
|
interfaces, and release-readiness gaps before those problems reach live
|
|
application deployments.
|
|
|
|
### 7. Boundaries Preserve Velocity
|
|
|
|
Enablement should make the layered architecture easier to use, not become a
|
|
shortcut for mutating infrastructure, cluster, platform, or application
|
|
responsibilities.
|
|
|
|
---
|
|
|
|
## What This Is (Conceptually)
|
|
|
|
This layer is:
|
|
|
|
* a **developer enablement** layer
|
|
* a home for **CI/CD and GitOps workflow patterns**
|
|
* a source of **workload templates, SDKs, and buildpacks**
|
|
* a **promotion handoff** surface between source repos and S5 deployments
|
|
* a future **developer portal** and self-service entry point
|
|
* a place to codify delivery knowledge into **repeatable automation**
|
|
|
|
---
|
|
|
|
## What This Is Not
|
|
|
|
This layer is not:
|
|
|
|
* the infrastructure substrate
|
|
* the Kubernetes runtime
|
|
* the shared platform-services layer
|
|
* the application deployment and operations layer
|
|
* the source forge, package/container registry, or runner substrate layer
|
|
* the source-code home for business workloads
|
|
* a replacement for repo-owned workplans, ADRs, or implementation decisions
|
|
|
|
It is the **delivery machinery** that helps the rest of Railiance change
|
|
safely and repeatedly.
|
|
|
|
---
|
|
|
|
## Direction of Evolution
|
|
|
|
This layer is expected to evolve toward:
|
|
|
|
* Standard **pipeline templates** for Railiance workloads
|
|
* Reusable **build and image promotion** conventions
|
|
* GitOps workflows with clear **review and rollback** expectations
|
|
* Handoff contracts with `railiance-forge` for **runner labels, package
|
|
credentials, registry endpoints, and artifact evidence**
|
|
* Reusable templates that cite the forge-owned **runner/GitOps ownership
|
|
contract** before depending on privileged labels or credentials
|
|
* Developer-facing **self-service templates** and portal entry points
|
|
* SDKs and examples that make platform capabilities easy to consume correctly
|
|
* Release evidence that S5 can use for **deployment readiness**
|
|
|
|
---
|
|
|
|
## Guiding Question
|
|
|
|
> **How can Railiance make the correct delivery path the easiest path, so workloads can move from source to production with speed, evidence, and clear ownership?**
|