Add CODEOWNERS, ADRs and PR template (#13)

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @sequra/developer-experience

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,54 @@
+✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂
+✂✂✂  REMOVE FROM THIS PART BEFORE SUBMITTING YOUR PULL REQUEST ✂✂✂
+✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂
+
+Here are some friendly reminders before submitting your pull request:
+
+- There should be a goal describing the motivation for this change.
+- Consider if this change is restricting current style or expanding it.
+
+YOU CAN REMOVE THE PARTS OF THE TEMPLATE THAT DO NOT APPLY TO YOUR PULL REQUEST
+
+✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂
+✂✂✂  REMOVE UP TO THIS PART BEFORE SUBMITTING YOUR PULL REQUEST ✂✂✂
+✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂✂
+
+### What is the goal?
+
+_Provide a description of the overall goal (you can usually use the one from the issue)_
+
+### Is this a rectricting or expanding change?
+
+_[RESTRICTING|EXPANDING] Restricting changes are those that limit the current style or add new rules, while expanding changes are those that remove rules or relax the current ones._
+
+### References
+* **Issue:** _jira issue goes here, if suggesting a new feature or change, please discuss it in an issue first_
+* **Related pull-requests:** _list of related pull-requests (comma-separated): #1, #2_
+* **Any other references:** _list of links to other references (comma-separated): link1, link2_
+
+### How is it being implemented?
+
+_Provide a description of the implementation_
+
+### Opportunistic refactorings
+
+_Have you improved the code/app in anyway? Explain what you did._
+
+### Caveats
+
+_If you find any, please describe all the special conditions._
+
+### How is it tested?
+
+_Automatic tests? Manual tests?_
+
+_If it cannot be tested explain why._
+
+_Add use cases if specs are incomplete or missing._
+
+### How is it going to be deployed?
+
+_If it does not require anything special, just write "Standard deployment". Otherwise, put the required steps._
+
+- [ ] _Step 1_
+- [ ] _Step 2_

docs/decisions/2022-10-25-use-markdown-architectural-decision-records.md

@@ -0,0 +1,170 @@
+# Use Markdown Architectural Decision Records
+An architecture decision record (ADR) is a document that captures an important architecture decision made along with its context and consequences.
+
+---
+**💡 Proposed 💡**
+* **Deciders:** @franmosteiro, @jaimevelaz
+* **Proposal date:** 25/10/2022
+* **Due date:** 01/11/2022
+* **Technical information:** None
+
+---
+### Contents
+* [Context and Problem Statement](./##context-and-problem-statement)
+* [Decision Drivers](./##decision-drivers)
+* [Considered Options](./##considered-options)
+* [Decision Outcome](./##decision-outcome)
+  * [ADR file name conventions](./###adr-file-name-conventions)
+  * [Suggestions for writing good ADRs](./###suggestions-for-writing-good-adrs)
+* [Credits](./##credits)
+
+## Context and Problem Statement
+### Context
+As the team grows, we find that there is a growing need for documenting better and more the technical decisions we make in our services.
+
+This is not important just to the current people in the teams, or to the ones to come and even for our future ourselves when we need to recheck why we did something or how we decided something, but also for other teams and coworkers to reflect their own decisions and this way, finding some kind of alignment in the technical part without patronizing the autonomy in the teams.
+
+In short, trying to maintain a good balance between them: autonomy, pragmatism, and a similar stack.
+
+### Hypothesis
+We think that by providing some base templating for **ADR generation** and using them for our services design decisions, we can make this goal of documenting more and better relatively easier, simpler, faster and ultimately more straightforward for teams, so they will only have to make use of them when creating a new feature or iterating older ones.
+
+### Experiment
+We propose using **ADRs** as a tool that **might help us document our technical and design decisions more and better**. And also we think that the best place to place them is near the code, using them as another good way to understand the bigger picture before jumping into the tests and production code to get the detail of the things documented in the ADRs firstly.
+
+Of course, this will be an initial approach and we expect the template to evolve and grow with the collaboration, experience and necessities of any of the teams! 😊
+
+## Decision Drivers
+* Incremental growth in the size and number of teams and services.
+* Lack of context on other teams owned services, tracing, telemetry etc.
+* Lack of context in decision-making and overall direction of services.
+* Looking to improve cross-team collaboration.
+* Need to enable teams to understand the bigger picture.
+
+## Considered Options
+* Use Google Drive and its online editing capabilities, through a Google Doc or Google Sheet.
+* Use Atlassian Jira, through the tool's planning tracker.
+* Use Atlassian Confluence (wiki) and create wiki-style ADRs.
+* Making use of source code version control, such as git, we could create a file for each ADR nearest to the code.
+  * [MADR](https://adr.github.io/madr/) 2.1.2 – The Markdown Architectural Decision Records.
+  * [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR".
+  * [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements.
+  * Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+  * Formless – No conventions for file format and structure.
+
+## Decision Outcome
+We want to record architectural decisions made in this project.
+
+**Which format and structure should these records follow?**
+
+**Choosen option:** ADRs and in particular the [MADR model](https://adr.github.io/madr/)(without the tooling), because
+
+* Implicit assumptions should be made explicit.
+  Design documentation is important to enable people to understand the decisions later on.  
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+* The MADR format is lean and fits our development style.
+* The MADR structure is comprehensible and facilitates usage & maintenance.
+* The MADR project is vivid.
+
+### ADR ownership and execution
+**Ownership** of the ADR during the drafting and validation process **belongs to the persons/teams that originally initiated it.**
+
+Among other things, **they will be responsible for:**
+
+* **Communicate**, through the necessary and appropriate channels and as many times as necessary, the entire content of the ADR (even before it is finalised or closed, in draft).
+
+* **Obtain the buy-in** of the interlocutors and/or teams involved in the change or improvement proposed by the ADR, including stakeholders, if applicable.
+
+* **By consent** (this means that there is no more appropriate or better proposal, so we go with this one), **the tech team should be aligned and aware** of the step with this new ADR and become part of their own technical decisions.
+
+* **Be advocates of the idea** behind the ADR even after it has gone live, **reminding and helping new teams and colleagues to keep it relevant in their designs.**
+
+### ADR file name conventions
+If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR file name convention.
+
+We prefer to use a file name convention that has a specific format. Based on [this other ADR in Simba](https://github.com/sequra/simba/blob/master/adr/2022-03-10-adr-ids-timestamps.md), we will choose this format:
+
+* yyyy-mm-dd-choose-database.md
+* yyyy-mm-dd-format-timestamps.md
+* yyyy-mm-dd-manage-passwords.md
+* yyyy-mm-dd-handle-exceptions.md
+
+Our file name convention:
+
+* Date of creation: yyyy-mm-dd
+* The name has a present tense imperative verb phrase. This helps readability and matches our commit message format.
+* The name uses lowercase and dashes (same as this repo). This is a balance of readability and system usability.
+* The extension is markdown. This can be useful for easy formatting.
+
+### ADR workflow suggestion
+```text
+⚠️ This is just a suggested workflow. The choosed workflow may depend on the necessities your team has around the ADR: sharing an idea, sharing an idea with some Proof of Concept, sharing the implementation of a new design approach etc.
+```
+
+1. Share a new **P**ull**R**equest including the ADR in the docs/decisions folder, to start the conversation with the related teams/peers.
+
+2. Start the conversation on this first PR until it is “accepted” or “rejected”. Meanwhile, add in this PR (or in another one related somehow to the ADR PR) the proposed changes.
+
+3. Before closing the PR containing the ADR, remember to update it with the correct status and the final decisions taken regarding the comments of the rest of the team.
+
+```text
+ℹ️ These are just suggestion. Please, feel encouraged to set the workflow better fits within your concrete necessities and let’s learn with the process
+```
+
+### ADR ‘status’ changes
+An ADR can go through these different states:
+
+* **🚧 WIP 🚧:** still working on the ADR, not yet released.
+* **💡 Proposed 💡:** already proposed to the team.
+* **🚫 Rejected 🚫:** the team has rejected the ADR, but we save it for traceability.
+* **✅ Accepted ✅:** the team has accepted the ADR.
+* **🕸 Deprecated 🕸:** the ADR has been deprecated (ex: tech stack change, library deprecation etc).
+* **🌱 Superseded by ADR-202x-xx-xx 🌱:** if an ADR supersedes an older ADR then the status of the older ADR is changed to "superseded by ADR-yyyy-mm-dd", and links to the new ADR.
+
+#### How do we know when an ADR is accepted/rejected
+There are several mechanisms that will allow us to know whether an ADR is accepted or not.  
+As a starting point, there are **two scenarios**:
+
+* The **ADR has a due date**: which means that it needs to be resolved by that date at the latest.
+* The **ADR does not have a due date**.
+
+Regardless of the starting point, there are a number of mechanisms that will allow us to know whether or not an ADR is accepted by the due date (whether closed or not).
+
+```text
+📝 Once shared with the team, we will review acceptance ideally on the basis of consensus, although we will accept consent if the lack of feedback/interactions in the team is significant and the change is reversible (1).
+```
+
+#### Artifacts to review:
+* If there is explicit approval ✅ in the PRs, at least, from the owner team (in the PR including the ADR).
+* If there are **opinions against** the ADR, they must be justified in the comments and have **explicit RC** (request changes) **PR reviews ⛔**
+* If there are still unresolved discussions against the ADR idea or, if there are, they have been resolved.
+
+```text
+📝 Once all the information has been reviewed or if the due date arrives, we will transition the ADR to the appropriate status: accepted or rejected.
+```
+
+### Suggestions for writing good ADRs
+Characteristics of a good ADR:
+* Rational: Explain the reasons for doing the particular AD. This can include the context (see below), pros and cons of various potential choices, feature comparisons, cost/benefit discussions, and more.
+* Specific: Each ADR should be about one AD, not multiple ADs.
+* Timestamps: Identify when each item in the ADR is written. This is especially important for aspects that may change over time, such as costs, schedules, scaling, and the like.
+* Immutable: Don't alter existing information in an ADR. Instead, amend the ADR by adding new information, or supersede the ADR by creating a new ADR.
+
+Characteristics of a good "Context" section in an ADR:
+* Explain your organization's situation and business priorities.
+* Include rationale and considerations based on social and skills makeup of your teams.
+* Include pros and cons that are relevant, and describe them in terms that align with your needs and goals.
+
+Characteristics of good "Consequences" section in an ADR:
+* Explain what follows from making the decision. This can include the effects, outcomes, outputs, follow-ups, and more.
+* Include information about any subsequent ADRs. It's relatively common for one ADR to trigger the need for more ADRs, such as when one ADR makes a big overarching choice, which in turn creates the need for smaller decisions.
+* Include any after-action review processes. It's typical for teams to review each ADR one month later, to compare the ADR information with what's happened in actual practice, to learn and grow.
+
+A new ADR may take the place of a previous ADR:
+* When an AD is made that replaces or invalidates a previous ADR, then a new ADR should be created.
+
+## Credits
+KUDOS to Joel Parker for sharing all this knowledge with us through [this repo](https://github.com/joelparkerhenderson/architecture-decision-record).
+
+## Links
+[(1) Reversible changes](https://www.businessinsider.com/amazon-jeff-bezos-letter-reversible-decisions-1997-hq2-new-york-2019-2?op=1)

docs/decisions/README.md

@@ -0,0 +1,4 @@
+# Architectural design records
+The idea is to provide a basic integrated ADR generation for #{your project}
+  - You can see an [index of ADRs here](./index.md)
+  - You can see the [base template here](./template.md)

docs/decisions/index.md

@@ -0,0 +1,7 @@
+# Architectural Decision Log
+
+This log lists the architectural decisions for [project name].
+
+* [ADR-2022-10-25](2022-10-25-use-markdown-architectural-decision-records.md) - Architectural Decision Records as a way for documenting design decisions
+
+For new ADRs, please use [template.md](template.md) as basis.

docs/decisions/template.md

@@ -0,0 +1,102 @@
+✂✂✂✂✂< REMOVE FROM THIS PART BEFORE SUBMITTING YOUR ADR ✂✂✂✂✂
+# ⚠️ Should this be an ADR?
+Are you in doubt if this document you or your team propose needs to be an Architectural Decision Record?
+
+Let's check it through several questions 😊
+
+Starting with a `stop question`:
+
+* ❓ Is this ADR related to a change in this specific application or service?
+✋ **If** the answer **is "no"**, which means that this ADR affects this application and others, **end this document here** and start writing a general Decision Record [here](https://sequra.atlassian.net/wiki/spaces/EN/pages/3771039771/Tech+Decision+Records#List-of-Tech-Decision-Records)
+👇 **If** the previous **answer is a "yes"**
+
+Let's **continue** with these other questions:
+
+* ❓ Will this ADR provoke a breaking changes or sensible modifications inside this application or services' engine, interfaces, APIs or [seams](https://archive.org/details/working-effectively-with-legacy-code/page/n51/mode/2up) `(look into chapter 4 of this book for the reference)` between domains?
+* ❓ Will this ADR introduce new architectural or software design patterns in the project (f.ex: big refactors which provide that an old feature can work in a new way, introducing a new technology/gem/package/etc ...)
+* ❓ Will this ADR impact other teams’ roadmaps or velocities meaningfully?
+* ❓ Does this ADR imply different approaches/options for which you want/need the opinion of the rest of the team?
+* ❓ Does this ADR modify/impact another existing or very similar ADR (superseeding or refining it)?
+
+Then, evaluate your answers:
+
+* 👉  If you checked any of those boxes, this topic does need an ADR.
+* 👉  If you didn’t check any of those boxes, doing an ADR is optional.
+
+**❗  Depending on your decision, either delete this section or delete this document!**
+
+✂✂✂✂✂< REMOVE FROM THIS PART BEFORE SUBMITTING YOUR ADR ✂✂✂✂✂
+
+# [short title of solved problem and solution]
+
+---
+* **Status:** [🚧🌱 wip | 💡 proposed | 🚫 rejected | ✅ accepted | 🕸 deprecated | … | ⬆️🌱 superseded by [ADR-0005](0005-example.md)] <!-- optional -->
+* **Deciders:** [list everyone involved in the decision] <!-- optional -->
+* **Proposal date:** [YYYY-MM-DD when the decision was proposed] <!-- optional -->
+* **Due date:** [YYYY-MM-DD when the decision is finally made] <!-- optional -->
+* **Technical Story:** [description | ticket/issue URL] <!-- optional -->
+---
+## Context and Problem Statement
+
+[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
+
+## Decision Drivers <!-- optional -->
+
+* [driver 1, e.g., a force, facing concern, …]
+* [driver 2, e.g., a force, facing concern, …]
+* … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+* [option 1]
+* [option 2]
+* [option 3]
+* … <!-- numbers of options can vary -->
+
+## Decision Outcome
+
+Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].
+
+### Positive Consequences <!-- optional -->
+
+* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
+* …
+
+### Negative Consequences <!-- optional -->
+
+* [e.g., compromising quality attribute, follow-up decisions required, …]
+* …
+
+## Pros and Cons of the Options <!-- optional -->
+
+### [option 1]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+* Good, because [argument a]
+* Good, because [argument b]
+* Bad, because [argument c]
+* … <!-- numbers of pros and cons can vary -->
+
+### [option 2]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+* Good, because [argument a]
+* Good, because [argument b]
+* Bad, because [argument c]
+* … <!-- numbers of pros and cons can vary -->
+
+### [option 3]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+* Good, because [argument a]
+* Good, because [argument b]
+* Bad, because [argument c]
+* … <!-- numbers of pros and cons can vary -->
+
+## Links <!-- optional -->
+
+* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
+* … <!-- numbers of links can vary -->