Wanja Krah
bd898e92d2
All checks were successful
Build, test and publish / verify (push) Successful in 8m15s
168 lines
8.5 KiB
Plaintext
168 lines
8.5 KiB
Plaintext
As developer
|
|
I want to separate landscape documentation and reusable engineering resources from Agile Dancers
|
|
so that I adhere to ADR1 and can start and maintain multiple projects with a complete, versioned engineering setup.
|
|
|
|
Status: REFINED
|
|
|
|
Architecture: ADR1, Application size (`adr/approved/ADR1_application-size.md` before migration).
|
|
|
|
Affected repositories:
|
|
|
|
- `agiledancers` (existing application repository)
|
|
- `landscape` (new repository)
|
|
- `engineering` (new repository)
|
|
|
|
## Intent
|
|
|
|
Create `landscape` and `engineering` on the existing Gitea server, under the same
|
|
owner as `agiledancers`. Check them out to `~/Projecten/git/landscape` and
|
|
`~/Projecten/git/engineering`.
|
|
|
|
Keep Agile Dancers working throughout the migration. Fully generalize the
|
|
engineering setup so another project can start with a ready-to-use pipeline
|
|
recipe. Moving application-specific helpers unchanged into another repository
|
|
does not satisfy this specification.
|
|
|
|
## Repository ownership
|
|
|
|
### Landscape
|
|
|
|
Move ADRs and specifications, including this specification, to `landscape`.
|
|
Maintain the capability and system map there, recording current boundaries and
|
|
leaving future business-system extraction to follow-up specifications. Each
|
|
specification identifies the repositories it affects.
|
|
|
|
Landscape also contains instructions for starting projects that use this setup,
|
|
including repository creation, use of the engineering project generator,
|
|
configuration, secrets setup, and engineering upgrades. Link to engineering's
|
|
technical usage instructions rather than maintaining duplicate instructions.
|
|
|
|
### Engineering
|
|
|
|
Move reusable skills, general engineering documentation, coding standards,
|
|
tooling, and generalized pipeline and deployment mechanisms to `engineering`.
|
|
Include templates and a project generator for new consumers.
|
|
|
|
Generalize the existing CI, deployment, formatting, standards, and coverage
|
|
helpers as needed. This includes helpers such as `ci/Pipeline.java`; substantial
|
|
generalization is part of S19 rather than deferred merely because it requires
|
|
more than a small configuration change.
|
|
|
|
Keep upstream skill files unchanged. Preserve their revision records, licenses,
|
|
and attribution, including the files currently recorded in `skills/upstream.json`.
|
|
|
|
### Application repositories
|
|
|
|
Keep implementation code, executable tests, fixtures, historical application
|
|
validation reports, and implementation and operational instructions with their
|
|
application. Keep project-specific configuration and adapters here, including
|
|
Compose configuration, deployment targets, secret references, and existing
|
|
maintainer-approved standards waivers. Do not copy application waivers into
|
|
defaults for other projects. Do not commit secret values.
|
|
|
|
Classify every existing resource in the ADR, specification, CI, deployment,
|
|
documentation, skills, and tooling folders. Record its destination and the reason
|
|
it moves or stays. For mixed resources, separate the general mechanism from
|
|
application configuration rather than assigning the whole folder one destination.
|
|
|
|
## Versioned consumption and generation
|
|
|
|
Release engineering as one package using semantic version tags such as `v1.0.0`.
|
|
Published tags are immutable; breaking changes require a new major version.
|
|
Consumers adopt upgrades explicitly and record both the selected tag and its
|
|
resolved commit. Reject a fetch when the tag no longer resolves to that commit.
|
|
|
|
Copy the selected engineering resources into a committed `generated/` folder in
|
|
each consuming project. Record their source and version. Treat these files as
|
|
generated output: make general changes in engineering and regenerate the local
|
|
copy. Regeneration replaces generated content, including removal of obsolete
|
|
generated files, without overwriting project-owned files outside that folder.
|
|
|
|
Provide a small project-local bootstrap script and version configuration outside
|
|
`generated/`. Add a Maven profile that invokes the script to regenerate from the
|
|
selected engineering version. The profile must work when `generated/` is absent;
|
|
it must not require generated tooling to bootstrap itself.
|
|
|
|
Ordinary local builds use the committed resources without downloading or
|
|
regenerating them each time. Access to engineering can be assumed for explicit
|
|
regeneration and CI. No Nexus or other artifact repository is required.
|
|
|
|
CI regenerates from the recorded tag and commit and fails if the resulting
|
|
generated files differ from the committed files, including added or removed
|
|
files. CI does not select a newer engineering release automatically.
|
|
|
|
Keep Maven verification, standalone Docker builds, CI, and agent instructions
|
|
working with these paths. A fresh application clone must not depend on sibling
|
|
repository checkouts or globally installed project skills.
|
|
|
|
## General pipeline recipe and project generator
|
|
|
|
Support Gitea Actions, Maven/Java, npm, and Docker Compose. Projects can select a
|
|
backend, a frontend, or both. Other build systems and deployment platforms are
|
|
outside this specification.
|
|
|
|
Make project names, module paths, image names, deployment servers and paths,
|
|
and healthchecks configurable. Provide shared build, test, image-build,
|
|
deployment, and rollback mechanisms. Application secrets remain configured by
|
|
the consuming project; engineering supplies the mechanism and instructions.
|
|
|
|
Provide a command that creates a local project skeleton from templates using a
|
|
project name and the selected components. Include pipeline workflows, project
|
|
configuration, bootstrap script, engineering version configuration, and agent
|
|
instructions. Repository creation and secrets configuration are documented
|
|
setup steps rather than actions performed by this generator.
|
|
|
|
The generator creates project-owned files such as `pom.xml`, workflows, and
|
|
Compose configuration once. Subsequent engineering upgrades automatically
|
|
replace only `generated/`. Supply upgrade instructions when project-owned files
|
|
also require changes. Keep these project-owned files thin by delegating shared
|
|
behavior to generated engineering resources.
|
|
|
|
Include a small example project in engineering that consumes the same recipe
|
|
and proves it works without hidden Agile Dancers assumptions. Validate its
|
|
deployment and rollback in an isolated test environment.
|
|
|
|
## Documentation and traceability
|
|
|
|
Start the new repositories with attributed snapshots. Record the source
|
|
repository and source commit; retain the existing history in Agile Dancers.
|
|
Extracting Git history into the new repositories is not required.
|
|
|
|
Update README, AGENTS, and affected links after moving files. Explain how agents
|
|
and maintainers locate landscape guidance, use the pinned engineering resources,
|
|
regenerate them, and adopt upgrades. Landscape guidance may be referenced at its
|
|
current revision; executable engineering resources remain pinned. Use fixed
|
|
commits where historical evidence needs a stable reference.
|
|
|
|
Repair links between moved specifications and application validation evidence.
|
|
Each application's README continues to describe its implementation and operation.
|
|
|
|
## Migration and acceptance criteria
|
|
|
|
Migrate incrementally, keeping the application working after each extraction.
|
|
Complete the following before considering S19 implemented:
|
|
|
|
1. Both new repositories exist in Gitea and at the agreed local checkout paths.
|
|
2. The resource classification is complete, destinations follow ADR1, and moved
|
|
files retain source attribution and applicable licenses.
|
|
3. Engineering has a tagged release, a documented generator and upgrade process,
|
|
and fully generalized mechanisms for the supported stack.
|
|
4. Agile Dancers consumes the recorded engineering tag and commit through
|
|
committed generated resources. Regeneration works from a clean checkout and
|
|
with `generated/` absent. CI detects generated-file drift and rejects a moved
|
|
tag without silently upgrading.
|
|
5. A clean Agile Dancers checkout passes the required build and test checks and
|
|
builds its Docker image without sibling checkouts. Its Gitea build workflow
|
|
succeeds with the new resource layout.
|
|
6. Agile Dancers deployment and rollback configuration is validated. Record any
|
|
behavior that cannot be verified without a production deployment as an
|
|
explicit validation limit.
|
|
7. The example project is generated from the recipe, builds and tests from a
|
|
clean checkout, and demonstrates deployment and rollback in an isolated
|
|
environment.
|
|
8. README, AGENTS, landscape onboarding instructions, and affected links explain
|
|
and correctly reference the resulting setup.
|
|
|
|
Production deployment is a separate action. Business capability extraction,
|
|
runtime system boundaries, and migration of application data are outside S19.
|