From 4bb48c98c4c656782c78b0b974f1386791c326be Mon Sep 17 00:00:00 2001 From: Ania Warzecha Date: Tue, 15 Apr 2025 17:58:04 +0200 Subject: [PATCH] Add first PDR --- .github/workflows/check-spelling.yml | 14 ++ README.md | 29 +++- cspell.json | 52 ++++++ decisions/001_plugins_apps_direction.md | 47 ++++++ decisions/template.md | 205 ++++++++++++++++++++++++ 5 files changed, 345 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/check-spelling.yml create mode 100644 cspell.json create mode 100644 decisions/001_plugins_apps_direction.md create mode 100644 decisions/template.md diff --git a/.github/workflows/check-spelling.yml b/.github/workflows/check-spelling.yml new file mode 100644 index 0000000..99c7d45 --- /dev/null +++ b/.github/workflows/check-spelling.yml @@ -0,0 +1,14 @@ +name: "Check spelling" +on: + pull_request: + types: [synchronize, opened] + +jobs: + spellcheck: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + - uses: streetsidesoftware/cspell-action@934c74da3775ac844ec89503f666f67efb427fed # v6.8.1 + with: + # Note: before changing this line, update the package.json's "check-spelling" script. + files: "**/*.{jsx,js,md,mdx}" diff --git a/README.md b/README.md index 290b0ca..5564da8 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,27 @@ -# decision-records -Quo Vadis Saleor? +
+

Saleor Decision Records šŸ§ 

+
+ +
+ šŸ  Website + ā€¢ + šŸ“š Docs + ā€¢ + šŸ“° Blog + ā€¢ + šŸ¦ Twitter + ā€¢ + šŸ’¬ Discord +
+ +## Quo valid Saleor? +In the spirit of transparency we are opening up our internal decision making process. When making a decision around how to fix a bug or introduce even a small change in the code you need to know what is the overall aim. Internally we write down those decisions. Even if these are implicit decisions done a few years ago, we are backfilling those and getting them up to date. + +## How decisions are made in Saleor? +We are following the concept of Decision Records for everything from technical RFCs, Architecture Decision Records, and Product Decision Records. Internally the process is very lean, we write a short doc, put it out to get feedback, and after a few days mark those as accepted. This way we make sure people can reference the decisions and are empowered to make daily decisions in line with the general direction. + +## What is this repository? +We would like to get more eyes on the decisions we are making especially when they are touching developers working with our open source bits. We regularly get pull requests we cannot accept because they are not in line with the direction we want to take. It's wasted energy and effort for the contributors and it's sad when we need to tell a fellow engineer their contribution is so far away it will just not do. We hope with this repository it's going to be easier for people to get where Saleor is going and make contributions along with it. In many cases this will also help engineers make decisions around their own solution, such that they will have less work in the future, once we introduce changes. + +## Decision Records concept +You can learn more about [Decision Records](https://github.com/joelparkerhenderson/decision-record) in a related repository \ No newline at end of file diff --git a/cspell.json b/cspell.json new file mode 100644 index 0000000..76e70df --- /dev/null +++ b/cspell.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json", + "words": [ + "adyen", + "applicating", + "atobarai", + "avalara", + "avatax", + "braintree", + "configurators", + "givex", + "graphene", + "htmx", + "idfilter", + "incentivized", + "klarna", + "klaviyo", + "magento", + "metastring", + "mirumee", + "mjml", + "noreferrer", + "psql", + "saleor", + "slugifying", + "turborepo", + "undiscounted", + "Å¼Ć³Å‚ta", + "noopener", + "Hono" + ], + "allowCompoundWords": true, + "useGitignore": true, + "language": "en-US", + "languageSettings": [ + { + "languageId": "markdown,mdx", + "ignoreRegExpList": [ + // Exclude code blocks. + "/^\\s*```[\\s\\S]*?^\\s*```/gm", + // Exclude links + "/\\[.*\\]\\(.*\\)/g", + // Exclude json code blocks + "/^\\s*```json[\\s\\S]*?^\\s*```/gm", + // Exclude graphql code blocks + "/^\\s*```graphql[\\s\\S]*?^\\s*```/gm", + // Exclude inline code + "/`.*`/g" + ] + } + ] + } \ No newline at end of file diff --git a/decisions/001_plugins_apps_direction.md b/decisions/001_plugins_apps_direction.md new file mode 100644 index 0000000..f515466 --- /dev/null +++ b/decisions/001_plugins_apps_direction.md @@ -0,0 +1,47 @@ +# 2025 Apps/Plugins direction + +Status: accepted + +Summary: What's our take on Plugins and Apps and the whole ecosystem of extending Saleor. + + +## Issue + +Historically Saleor had Plugins as a way to implement third party integrations and customer solutions. At some point we moved towards Apps. We still have plugins in the codebase though. It's not always clear how we stand with the general direction. + +### Plugins general direction + +In general we do need and want to maintain the plugins we have in the codebase. This means: + +- we do not build any new features in these plugins +- we fix bugs and port fixes to previous versions of saleor/saleor +- we treat it as normal functionality we have + +### Apps general direction + +Apps is our current preferred ecosystem of building new extensions. We also maintain our own App Store available in the Dashboard and a public facing one on [apps.saleor.io](http://apps.saleor.io). + +We have apps that we host, we have example apps we do not intend to hos. We have open source apps and closed source apps intended for cloud users only. + +General decision making around apps: + +- app will be hosted and closed source if we think itā€™s important for us to maintain it for enterprise clients and an added value for money for our clients +- app will be hosted and open source if we think itā€™s critical for Saleor to have a specific integration or a specific app available for everyone +- app will be open source and not hosted in all other cases + +The list of supported apps is up to date on Dashboard. [apps.saleor.io](http://apps.saleor.io) holds a list of both our hosted apps, open source apps and apps built by third party companies. + + +### Plugins list with the intended future + +- Adyen - we have an app replacement for Cloud users, we want to remove the plugin as soon as possible +- Authorize.net - we have an app replacement example in [saleor/saleor-app-payment-authorize.net](https://github.com/saleor/saleor-app-payment-authorize.net) +- braintree - intended to be replaced by an app +- np_atobarai - we do not intend to build a replacement, and we want to remove it as soon as possible +- razorpay - we do not intend to build a replacement, and we want to remove it as soon as possible +- stripe - we are building an open-source app replacement in [saleor/apps](https://github.com/saleor/apps/tree/main/apps/stripe) +- admin_email - will be folded into [saleor/saleor](https://github.com/saleor/saleor) code +- avatax/avalara - we have an app replacement available in [saleor/apps](https://github.com/saleor/apps/tree/main/apps/avatax) +- openid_connect - will likely be replaced by an External Auth API and folded into [saleor/saleor](https://github.com/saleor/saleor) core code +- sendgrid - there is an app replacement [saleor/apps](https://github.com/saleor/apps/tree/main/apps/smtp) +- user_email - there is an app replacement in [saleor/apps](https://github.com/saleor/apps/tree/main/apps/smtp) \ No newline at end of file diff --git a/decisions/template.md b/decisions/template.md new file mode 100644 index 0000000..1e20721 --- /dev/null +++ b/decisions/template.md @@ -0,0 +1,205 @@ +# Title (short present tense imperative up to 50 characters) + +Status: request for comments | proposed | accepted | rejected | deprecated | superseded + +Summary: briefly explain the current position and any needs. + + +## Issue + +Describe the issue you want to address. Leave no questions about why youā€™re addressing this issue now. + +Follow a minimalist approach. Address only the issues that need addressing at various points in the life cycle. + +You may want to add some grouping information, such as tags, keywords, knowledge base links, etc. + + +## Assumptions + +Describe any underlying assumptions in the environment in which youā€™re making the decision. + +Be sure to address any relevant quality attributes a.k.a. cross-functional requirements. + +Example assumptions may involve scope, cost, schedule, technology, resource availability, quality of service needs, service level agreements, and so on. + +Note that environmental constraints (such as accepted technology standards, enterprise architecture, commonly employed patterns, and so on) might limit which options you consider. + + +## Constraints + +Capture any additional constraints to the environment that this decision might pose. + +Be sure to address any relevant quality attributes a.k.a. cross-functional requirements, as above. + +Example constraints may involve platform choices, vendor selections, the ease of decision reversibility, etc. + + +## Positions + +List the positions, which are the viable options that you are considering, or have considered. + +Use facts and data, not opinions. The positions can often require long explanations, sometimes even models and diagrams. + +This doesn't need to be an exhaustive list; however, you donā€™t want to hear the question "Did you think about...?" during a final review, because this would lead to loss of credibility and questioning of other architectural decisions. + +This section also helps ensure that you heard othersā€™ opinions; explicitly stating other opinions helps enroll their advocates in your decision. + + +### Cost analysis (optional) + +Summary: briefly explain this section, and ideally highlight any outliers. + +Examples: + + * Initiating, such as setup costs, time, and resources. + + * Operating, such as support and maintenance + + * Training, such as upskilling and change management + + * Licensing, such as contract agreements and legal commitments + + * Metering, such as bandwidth and CPU usage + + +### SWOT analysis (optional) + +Summary: briefly explain this section, and ideally highlight any outliers. + + * Strengths + + * Weaknesses + + * Opportunities + + * Threats + + +### PEST analysis (optional) + +Summary: briefly explain this section, and ideally highlight any outliers. + + * Political factors + + * Economic factors + + * Social factors + + * Technological factors + +Some teams like to add these as their own categories: + + * Legal factors - we prefer to have these in the political factors. + + * Regulatory factors - we prefer have these in the political factors. + + * Environmental factors - we prefer to have these in the economic factors. + + * Demographic factors - we prefer to have these in the social factors. + + +### Other analysis (add your own ideas here) + +Add your own ideas here... + + +## Opinions + +Summary: briefly explain this section, and ideally highlight any outliers. + + * By the team, ideally written by the actual teammate. + + * By other internal stakeholders, ideally written by the actual stakeholder. + + * By external people, such as third-party advisors, evaluators, reviewers, etc. + +For each opinion, be clear about: + + * Who is providing the opinion + + * What other candidates were considered, + + * How did the author evaluate the candidates? + + * Why did the author choose the winner? + + * What is happening since then? + + * Knowing what you know now, what would you advise people to do differently? + + +### Opinion 1 title (add yours here) + +Summary: briefly explain this section, and ideally highlight any outliers. + +Explain your opinion here. + + +### Opinion 2 title (add yours here) + +Summary: briefly explain this section, and ideally highlight any outliers. + +Explain your opinion here. + + +### Opinion 3 title (add yours here) + +Summary: briefly explain this section, and ideally highlight any outliers. + +Explain your opinion here. + + +## Argument + +Summary: briefly explain this section, and ideally highlight any outliers. + +Explain why you selected a position. + +Decisions should be purpose-driven. To show accountability, explicitly map your decisions to the objectives or requirements. + +The argument is probably as important as the decision itself. + +This doesn't need to be an exhaustive write-up; however, you donā€™t want to hear the question "Did you think about...?" during a final review, because (as above) this would lead to loss of credibility and questioning of other architectural decisions. + + +## Implications + +Summary: briefly explain this section, and ideally highlight any outliers. + +Clearly state your decisionā€™s implications. This can be very effective in gaining buy-in and creating a roadmap for execution. + +For example, a decision might introduce a need to make other decisions, create new requirements, or modify existing requirements; pose additional constraints to the environment; require renegotiating scope or schedule with customers; or require additional staff training. + + +## Related decisions + +Summary: briefly explain this section, and ideally highlight any outliers. + +List any related decisions here. + +Weā€™ve found that in practice, a traceability matrix, decision trees, or metamodels are more useful. Metamodels are useful for showing complex relationships diagrammatically (such as Rose models). + + +## Related requirements + +Summary: briefly explain this section, and ideally highlight any outliers. + +List any related requirements here. + +Weā€™ve found it more convenient to reference a traceability matrix. You can assess each decisionā€™s contribution to meeting each requirement, and then assess how well the requirement is met across all decisions. If a decision doesnā€™t contribute to meeting a requirement, then donā€™t make that decision. + + +## Related artifacts + +List any related artifacts here. + +Examples are any scope documents, planning documents, business process models, etc., that this decision impacts. + +## Related principles + +If the enterprise has an agreed-upon set of principles, make sure the decision is consistent with one or more of them. This helps ensure alignment along domains or systems. + + +## Related notes + +Because decision-making processes can take significant time, weā€™ve found it useful to capture notes and issues that the team discusses during the socialization process. \ No newline at end of file