[doc] Update ADRs from PR review comments

2022-09-06 19:28:11 +02:00
1 parent cbbe0e0cb0
commit 898454510d
@@ -1,5 +1,5 @@
 ---
-title: Architecture Design Decisions
+title: Architecture Decisions
 sidebar: pmd_sidebar
 permalink: pmd_projectdocs_decisions.html
 last_updated: July 2022
@@ -6,7 +6,7 @@ sidebaractiveurl: /pmd_projectdocs_decisions.html
 adr: true
 # Proposed / Accepted / Deprecated / Superseded
 adr_status: "Proposed"
-last_updated: July 2022
+last_updated: September 2022
 ---

 # Context
@@ -31,7 +31,7 @@ See also the blog post [Documenting Architecture Decisions](https://cognitect.co
 by Michael Nygard.

 There are many templates around to choose from. <https://github.com/joelparkerhenderson/architecture-decision-record>
-gives a nice summary.
+gives a nice summary. The page <https://adr.github.io/> gives a good overview on ADR and for adr-related tooling.

 # Decision

@@ -39,9 +39,19 @@ We will document the decisions we make as a project as a collection of "Architec
 In order to keep it simple, we will use only a simple template proposed by Michael Nygard.
 The documents are stored together with the source code and are part of the generated documentation site.

+A new ADR should be proposed with a pull request to open the discussion.
+The initial status of the new ADR is "Proposed". When maintainer consensus is reached during the PR
+review, then the status is changed to "Accepted" when the PR is merged.
+A new entry in the "Change History" section should be added, when the PR is merged.
+
+In order to propose a change to an existing ADR a new pull request should be opened which modifies the ADR.
+The change can be to amend the ADR or to challenge it and maybe deprecate it. A new entry in the
+"Change History" section should be added to summary the change. When maintainer consensus is reached
+during the PR review, then the PR can be merged and the ADR is updated.
+
 # Status

-{{ page.adr_status }}
+{{ page.adr_status }} (Last updated: {{ page.last_updated }})

 # Consequences

@@ -50,3 +60,9 @@ and can read the context and consequences of the decisions. This will likely als
 as the decisions need to be formulated and written down. Everybody is on the same page.

 However, this also adds additional tasks, and it takes time to write down and document the decisions.
+
+# Change History
+
+2022-09-06: Added section "Change History" to the template. Added "Last updated" to "Status" section.
+
+2022-07-28: Proposed initial version.
@@ -6,7 +6,7 @@ sidebaractiveurl: /pmd_projectdocs_decisions.html
 adr: true
 # Proposed / Accepted / Deprecated / Superseded
 adr_status: "Proposed"
-last_updated: July 2022
+last_updated: September 2022
 ---

 # Context
@@ -39,27 +39,31 @@ and to keep it within bounds and therefore maintainable we came up with the foll
 * For (unit) testing, Kotlin can be used in `pmd-core` and in the language modules. The test frameworks can also
  use Kotlin (`pmd-test` doesn't yet, `pmd-lang-test` does already).
 * Additionally: from now on, we allow to have the individual language modules be implemented in different languages
-  when it makes sense. So, a language module might decide to use plain Java (like now) or also Kotlin
-  (or other languages if it fits).
+  when it makes sense. So, a language module might decide to use plain Java (like now) or also Kotlin.
 * When mixing languages (e.g. Java + Kotlin), we need to care that the modules can still be used with plain Java.
  E.g. when writing custom rules: `pmd-java` provides a couple of APIs for rules (like symbol table, type resolution)
  and we should not force the users to use Kotlin (at least not for language modules which already exist and
  for which users might have written custom rules in Java already).
 * It is also possible to write the entire language module in Kotlin only. Then the rules would be written in Kotlin
  as well. And the possible problems when mixing languages are gone. But that applies only for new language modules.
-  For compatibility reasons an existing language modules shouldn't be rewritten into Kotlin. That would be a
+* When refactoring an existing language module from Java only to introduce Kotlin, care needs to be taken to
+  not make incompatible changes. If compatibility (binary or source) can't be maintained, then that would be a
  major version change.

 # Status

-{{ page.adr_status }}
+{{ page.adr_status }} (Last updated: {{ page.last_updated }})

 # Consequences

 Allowing more Kotlin in PMD can attract new contributions. It might make it easier to develop small DSLs.
-Also, other languages than Kotlin could be used, e.g. for `pmd-scala` Scala might make sense.
+In the future we might also consider to use other languages than Kotlin, e.g. for `pmd-scala` Scala might make sense.

-On the other side, other IDEs than IntelliJ IDEA will have a difficult time to deal with PMD's source code.
-Eclipse can't be used practically anymore.
+On the other side, other IDEs than IntelliJ IDEA will have a difficult time to deal with PMD's source code
+when Kotlin is used. Eclipse can't be used practically anymore.

 Maintaining a polyglot code base with multiple languages is likely to be more challenging.
+
+# Change History
+
+2022-07-28: Proposed initial version.
@@ -21,8 +21,14 @@ What is the change that we're proposing and/or doing?

 # Status

-{{ page.adr_status }}
+{{ page.adr_status }} (Last updated: {{ page.last_updated }})

 # Consequences

 What becomes easier or more difficult to do because of this change?
+
+# Change History
+
+YYYY-MM-DD: Add xyz.
+
+YYYY-MM-DD: Proposed initial version.