luigidemasi commented on issue #163:
URL: https://github.com/apache/camel-kit/issues/163#issuecomment-6945411861

   >It would be supercool if there were a document similar to Kit's 
design-spec.md but up to date with the implementation. I don't like the 
"amendment" concept that seems to describe a change on top of the baseline. 
Cumulative amendments just make documents hard to understand. It is unclear if 
design-spec.md should be kept up to date with "minor" changes or not. Also, 
having some pipelines describing greenfield development and some describing a 
change set on top of that looks confusing.
   @janihur thanks for the detailed example. The problems you 
describe—superseded decisions resurfacing and neither set of documents 
describing the complete system—deserve explicit handling.
   
   I’ve opened [#182](https://github.com/apache/camel-kit/issues/182) to track 
this. The proposal is to maintain:
   
   - Current system documentation, updated in place so it remains readable 
without combining successive amendments.
   - Architecture Decision Records, preserving the context, alternatives, 
tradeoffs and consequences of significant decisions, with clear links when 
decisions are superseded.
   
   The intended workflow would also let you consolidate existing pipeline 
documents and the actual implementation into a coherent system description, 
without rerunning the original pipelines. Pipeline artifacts would remain 
available as history.
   
   Changes affecting documented behavior, contracts or architecture should 
update the relevant sections, including changes made outside a pipeline. That 
would not require an ADR or a full design cycle for every small edit.
   
   Today, the documents are primarily pipeline-scoped; automatic reconciliation 
into a complete current-system description is not supported, but you have all 
the informations to askk an agent to create one. #164 addressed the initial 
existing-project workflow, while #182 covers this additional lifecycle and 
requires documentation of its limitations.
   
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to