[doc] Add architecture decision records #4072
Conversation
adangel
added
in:documentation
adangel
changed the title
Generated by 🚫 Danger |
|
This is a great idea! I have a few questions/ topics for general discussion. I'll add my comments to the kotlin ADR as review comments
I think we should document these processes in ADR 0... Or at least sketch the expected "lifecycle" of an ADR, with different statuses I'm wondering about the scope of ADRs. Do "architecture decisions" include eg proposals for large features (like eg JEPs)? Is there a difference with RFC issues? Maybe issues are more implementation related. Would the following be appropriate topics for ADRs, or am I missing the point:
|
Good points - I've added a short description what I think could work in the ADR-1. Basically we use PRs to propose new ADRs and modify existing ADRs.
Hm... I don't think, that large features should be written as ADRs. A feature sounds too specific for me. Maybe if we can come up with a general direction of what PMD should be or shouldn't be, that might be an ADR. E.g. (don't take these examples serious... 😄 ) "PMD will concentrate the work on the core functions needed for static analysis. Any integration into plugins, tools, etc. is out of scope for the project" or "PMD won't use GitHub anymore, because it is not open source" or "PMD will only support languages where free tooling is available" or "PMD will drop support for Windows". RFC issues... I could imagine, that an ADR could originate from an RFC issue. So that the discussion on the issue leads us to writing the result down as an ADR. If issues are implementation related, that could be too specific for an ADR.
I think, these are all good examples for ADRs. I'd say it's a bit of a mixture of architecture and processes (policies). |
adangel
changed the title
[doc] Add architecture decision records pmd#4072
Describe the PR
This is a first draft on adding explicit decision records to our project.
It came up as a question in #3766 about Kotlin usage.
I'm not sure in what details we would need to describe the decisions or which decisions at all. I guess, we need to learn this over time.
Feel free to give feedback or ask questions - the goal is to have the decision records as an agreement and understandable by everybody.
I've integrated these into the doc site, they appear under "Project documentation":
But since these documents are simple markdown files, they can also be seen directly on github.