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]
