Introduce ADR's to the project (#1345)

* Introduce ADR's to the project

* Added an ADR about extension points in the projects, implemented CR changes

* Create a list to accepted/proposed/rejected ADs

Author: norberttech

documentation/adrs.md

@@ -0,0 +1,33 @@
+# Architecture Decision Record
+
+# What are ADRs?
+Architecture Decision Records (ADRs) are structured documents that capture significant architectural decisions made during the development of this project. 
+
+Each ADR explains:
+- **The context**: Why the decision was necessary.  
+- **The decision**: What was decided and why.  
+- **The consequences**: The impact of the decision, both positive and negative.  
+
+ADRs act as a single source of truth for important design and architectural choices, ensuring that everyone involved in the project has a shared understanding of why things are the way they are.
+
+## How to Use ADRs in This Project
+**Follow Existing ADRs**: ADRs are mandatory to follow unless explicitly overridden by a new ADR. This ensures consistency in decision-making across the project.
+
+> Whenever ADR is merged into the main branch, it is considered accepted and must be followed by all contributors.
+
+**Propose New ADRs for Significant Decisions**:
+
+- If you encounter a situation that requires a significant architectural or design change, you must create a new ADR.
+- Use the provided [ADR Template](/documentation/adrs/template.md) to create your proposal.
+- Submit the ADR via a pull request and engage in a discussion with maintainers and contributors.
+- **Document Decisions Transparently**: All significant decisions must be documented. This includes not only what was decided but also the alternatives that were considered and why they were rejected.
+
+## Index of ADRs
+
+### [Accepted AD](https://github.com/flow-php/flow/pulls?q=is%3Apr+is%3Aclosed+is%3Amerged+label%3AAD+)
+- [2025-01-07: Static Analysis Baseline](/documentation/adrs/static-analysis-baseline.md)
+- [2025-01-09: Extension Points](/documentation/adrs/extension-points.md)
+
+### [Proposed AD](https://github.com/flow-php/flow/pulls?q=is%3Apr+is%3Aopen+label%3AAD+)
+
+### [Rejected AD](https://github.com/flow-php/flow/pulls?q=is%3Apr+is%3Aclosed+is%3Aunmerged+label%3AAD+)

documentation/adrs/extension-points.md

@@ -0,0 +1,77 @@
+# Extension Points
+
+Proposed by: @norberttech  
+Date: 2025-01-09
+
+## Context
+---
+
+Flow is a framework, and as all frameworks, it should provide extension points for developers to hook into the framework and extend its functionality.
+
+How to find an extension point? 
+
+Easy, look for interfaces! For example take a look at `\Flow\ETL\Cache` which is 
+an interface with few implementations. Thanks to the interface, you can easily
+create your own implementation and use it in the framework.
+
+Most of the extension points exposed through `\Flow\ETL\Config` where you can
+replace a default implementations of various interfaces with those that better 
+fit your needs.
+
+Those extension points are there by design and should follow the backward compatibility policy. 
+
+Are there any other extension points that we should consider?
+
+Yes... Unfortunately, each class that is not marked final and that is being somehow
+injected into the DataFrame must be considered as an extension point. 
+
+Why? Because nothing prevents developers from extending those classes and injecting 
+their custom version into the DataFrame.
+
+Those extension points can't be covered by our backward compatibility policy. 
+
+## Decision
+---
+
+**Closed by default**
+
+All classes should be marked as `final` and whenever we need to expose an extension point,
+we should do it through an interface.
+
+**Always possible to open later**
+
+In a justifiable cases, we can expose extension points through abstract classes or
+simply allowing people to extend the class. Those must always be approved by one of
+the core contributors. 
+
+**No guarantee and support for workarounds**
+
+Developers can still use reflections or dedicated tools to "unfinalize" Flow classes, 
+but we do not guarantee backward compatibility for those cases and everyone should 
+do it at their own risk. As a Flow PHP maintainers, we also reserve the right to
+not provide any help or support for those cases.
+
+## Pros & Cons
+---
+
+- zero risk of breaking accidentally backward compatibility promise
+- more predictable behavior
+- reduced cost of maintaining backward compatibility
+- easier to find an actual extension points
+- impossible to mock classes that aren’t marked as `final` in tests (which is a good thing, users shouldn’t mock Flow classes in their test suites)
+
+## Alternatives Considered (optional)
+---
+
+Alternatively we could take similar approach to Symfony and mark classes as `final`
+[when it makes sense](https://github.com/symfony/symfony/issues/15233#issuecomment-1566682054)
+but this approach is too easy to get abused. 
+
+Plus, changing non-final class into a final one is much bigger BC break
+then the other way around.
+
+## Links and References (optional)
+---
+
+- [When to declare classes final](https://ocramius.github.io/blog/when-to-declare-classes-final/)
+- [Final Classes by default, why?](https://matthiasnoback.nl/2018/09/final-classes-by-default-why/)

documentation/adrs/static-analysis-baseline.md

@@ -0,0 +1,50 @@
+# Static Analysis Baseline
+
+Proposed by: @norberttech
+Date: 2025-01-07
+
+## Context
+---
+
+After removal of Psalm and making PHPStan the main static analysis tool, 
+we looked again into hardening the static analysis configuration.
+
+We had three globally ignored errors in phpstan configuration
+
+- identifier: argument.type
+- identifier: missingType.iterableValue
+- identifier: missingType.generics
+
+All of the above were significantly reducing the value of static analysis and 
+code quality.
+
+One of the proposed approaches was to use a baseline file to suppress those errors
+in the existing codebase and gradually remove them.
+
+There are few problems with this approach, but the most significant one is that once the baseline is introduced, 
+it needs to be maintained.  
+Whenever the code is changed, the baseline needs to be updated, which is an opportunity to also suppress new errors.  
+This means that maintainers would not only need to go through the code changes
+but also through the baseline file, which is not the best use of their very limited and valuable time anyway.
+
+## Decision
+---
+
+We **must not** use baseline for static analysis. 
+Instead, errors can be suppressed by annotations in the codebase or globally
+in the static analysis tool configuration.
+
+Error suppression should be considered an edge case and should be used sparingly.
+Core contributors should review and approve all suppression annotations.
+
+## Pros & Cons
+---
+
+- The codebase will be cleaner and more maintainable.
+- More predictable and stricter types.
+- Less maintenance overhead related to managing the baseline.
+
+## Links and References
+---
+
+- #1329

documentation/adrs/template.md

@@ -0,0 +1,43 @@
+# [Decision Title]
+
+Proposed by: @author_github_username
+Date: YYYY-MM-DD
+
+## Context
+---
+
+`// Todo: Describe context here`
+
+> What is the current situation or issue that needs addressing?  
+> Why is this decision necessary?  
+> Any relevant background or constraints.
+
+## Decision
+---
+
+`// Todo: Describe the decision here`
+
+> What is the decision being made?  
+> State it clearly and concisely.
+
+## Pros & Cons
+---
+
+`// Todo: Describe the consequences here`
+
+> What are the outcomes or implications of this decision?  
+> Highlight both positive and negative impacts.
+
+
+## Alternatives Considered (optional)
+---
+
+`// Todo: Describe the alternatives here`
+
+> Briefly describe any alternatives that were considered.  
+> Why were they not chosen?
+
+## Links and References (optional)
+---
+
+> Include any supporting documents, links to issues, pull requests, or discussions that provide context.

documentation/contributing.md

@@ -6,6 +6,11 @@ Even that we are supporting 3 PHP versions at time, we are using the lowest supp
 
 For the code coverage, please install [pcov](https://pecl.php.net/package/pcov).
 
+### Before you change anything
+
+Please make sure that you are aware of our [Architecture Decision Records](/documentation/adrs.md).
+It's mandatory to follow all of them without any exceptions unless explicitly overridden by a new ADR.
+
 ### Prepare Project:
 
 ```shell

web/landing/assets/styles/app.css

@@ -186,4 +186,8 @@ code {
 
 #documentation-page code {
     @apply text-orange-100;
+}
+
+#documentation-page blockquote {
+    @apply border-l-4 border-orange-100 p-2 bg-blue-300 mb-3;
 }

web/landing/src/Flow/Website/Service/Markdown/LeagueCommonMarkConverterFactory.php

@@ -9,6 +9,7 @@
 use League\CommonMark\Extension\CommonMark\Node\Inline\Link;
 use League\CommonMark\Extension\ExternalLink\ExternalLinkExtension;
 use League\CommonMark\Extension\FrontMatter\FrontMatterExtension;
+use League\CommonMark\Extension\Mention\MentionExtension;
 use League\CommonMark\Extension\Table\TableExtension;
 
 final class LeagueCommonMarkConverterFactory
@@ -20,13 +21,26 @@ public function __invoke() : CommonMarkConverter
                 'open_in_new_window' => true,
                 'noreferrer' => 'all',
             ],
+            'mentions' => [
+                'github_handle' => [
+                    'prefix' => '@',
+                    'pattern' => '[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}(?!\w)',
+                    'generator' => 'https://github.com/%s',
+                ],
+                'github_issue' => [
+                    'prefix' => '#',
+                    'pattern' => '\d+',
+                    'generator' => 'https://github.com/flow-php/flow/issues/%d',
+                ],
+            ],
         ];
 
         $converter = new CommonMarkConverter($config);
 
         $converter->getEnvironment()
             ->addExtension(new ExternalLinkExtension())
             ->addExtension(new FrontMatterExtension())
+            ->addExtension(new MentionExtension())
             ->addExtension(new TableExtension())
             ->addRenderer(FencedCode::class, new FlowCodeRenderer(), 0)
             ->addRenderer(Link::class, new FlowLinkRenderer(), 0);

web/landing/templates/documentation/navigation.html.twig

@@ -25,6 +25,9 @@
             <li>
                 <a href="/documentation/dsl#dsl-functions">DSL References</a>
             </li>
+            <li>
+                <a href="/documentation/adrs">Architecture Decision Records</a>
+            </li>
             <li>
                 <a rel="noopener noreferrer" target="_blank" href="https://github.com/orgs/flow-php/projects/1">Project Roadmap</a>
             </li>