diff --git a/website/docs/contributing/ADRs/ADRs.md b/website/docs/contributing/ADRs/ADRs.md new file mode 100644 index 0000000000..95630b90fb --- /dev/null +++ b/website/docs/contributing/ADRs/ADRs.md @@ -0,0 +1,39 @@ +--- +title: ADR Overview +--- + +## Introduction {#introduction} + +Architectural decision records are a record of design decisions we have made in the past because we belived they would help our code quality over time. Any ADR can be challenged, but two conditions must be met to change an ADR: +1. The proposed solution must provide a tangible benefit in terms of code quality. +2. The benefits of the proposed solution must outweigh the effort of retroactively changing the entire codebase. +One such example is the decision to re-write Unleash to TypeScript. + +## Overarching ADRs + +These ADRs describe decisions that concern the entire codebase. They apply to back-end code, front-end code, and code that doesn't neatly fit into either of those categories. + +* [Domain language](./overarching/domain-language.md) + +## Back-end ADRs + +We are in the process of defining ADRs for the back end. At the time of writing we have created the following ADRS: + +* [Naming](./back-end/naming.md) +* [Preferred export](./back-end/preferred-export.md) + +## Front-end ADRs + +We have created a set of ADRs to help guide the development of the front end: + +* [Component naming](./front-end/component-naming.md) +* [Interface naming](./front-end/interface-naming.md) +* [Preferred component props usage](./front-end/preferred-component-props-usage.md) +* [Preferred export](./front-end/preferred-export.md) +* [Preferred function type](./front-end/preferred-function-type.md) +* [Preferred style import placement](./front-end/preferred-styles-import-placement.md) +* [Preferred styling method](./front-end/preferred-styling-method.md) +* [Preferred data mutation method](./front-end/preferred-data-mutation-method.md) +* [Preferred data fetching method](./front-end/preferred-data-fetching-method.md) +* [Preferred folder structure](./front-end/preferred-folder-structure.md) +* [Preferred form architecture](./front-end/preferred-form-architecture.md) \ No newline at end of file diff --git a/website/docs/contributing/backend/ADR/naming.md b/website/docs/contributing/ADRs/back-end/naming.md similarity index 100% rename from website/docs/contributing/backend/ADR/naming.md rename to website/docs/contributing/ADRs/back-end/naming.md diff --git a/website/docs/contributing/backend/ADR/preferred-export.md b/website/docs/contributing/ADRs/back-end/preferred-export.md similarity index 100% rename from website/docs/contributing/backend/ADR/preferred-export.md rename to website/docs/contributing/ADRs/back-end/preferred-export.md diff --git a/website/docs/contributing/frontend/ADR/component-naming.md b/website/docs/contributing/ADRs/front-end/component-naming.md similarity index 100% rename from website/docs/contributing/frontend/ADR/component-naming.md rename to website/docs/contributing/ADRs/front-end/component-naming.md diff --git a/website/docs/contributing/frontend/ADR/interface-naming.md b/website/docs/contributing/ADRs/front-end/interface-naming.md similarity index 100% rename from website/docs/contributing/frontend/ADR/interface-naming.md rename to website/docs/contributing/ADRs/front-end/interface-naming.md diff --git a/website/docs/contributing/frontend/ADR/preferred-component-props-usage.md b/website/docs/contributing/ADRs/front-end/preferred-component-props-usage.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-component-props-usage.md rename to website/docs/contributing/ADRs/front-end/preferred-component-props-usage.md diff --git a/website/docs/contributing/frontend/ADR/preferred-data-fetching-method.md b/website/docs/contributing/ADRs/front-end/preferred-data-fetching-method.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-data-fetching-method.md rename to website/docs/contributing/ADRs/front-end/preferred-data-fetching-method.md diff --git a/website/docs/contributing/frontend/ADR/preferred-data-mutation-method.md b/website/docs/contributing/ADRs/front-end/preferred-data-mutation-method.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-data-mutation-method.md rename to website/docs/contributing/ADRs/front-end/preferred-data-mutation-method.md diff --git a/website/docs/contributing/frontend/ADR/preferred-export.md b/website/docs/contributing/ADRs/front-end/preferred-export.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-export.md rename to website/docs/contributing/ADRs/front-end/preferred-export.md diff --git a/website/docs/contributing/frontend/ADR/preferred-folder-structure.md b/website/docs/contributing/ADRs/front-end/preferred-folder-structure.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-folder-structure.md rename to website/docs/contributing/ADRs/front-end/preferred-folder-structure.md diff --git a/website/docs/contributing/frontend/ADR/preferred-form-architecture.md b/website/docs/contributing/ADRs/front-end/preferred-form-architecture.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-form-architecture.md rename to website/docs/contributing/ADRs/front-end/preferred-form-architecture.md diff --git a/website/docs/contributing/frontend/ADR/preferred-function-type.md b/website/docs/contributing/ADRs/front-end/preferred-function-type.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-function-type.md rename to website/docs/contributing/ADRs/front-end/preferred-function-type.md diff --git a/website/docs/contributing/frontend/ADR/preferred-styles-import-placement.md b/website/docs/contributing/ADRs/front-end/preferred-styles-import-placement.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-styles-import-placement.md rename to website/docs/contributing/ADRs/front-end/preferred-styles-import-placement.md diff --git a/website/docs/contributing/frontend/ADR/preferred-styling-method.md b/website/docs/contributing/ADRs/front-end/preferred-styling-method.md similarity index 100% rename from website/docs/contributing/frontend/ADR/preferred-styling-method.md rename to website/docs/contributing/ADRs/front-end/preferred-styling-method.md diff --git a/website/docs/contributing/ADRs/overarching/domain-language.md b/website/docs/contributing/ADRs/overarching/domain-language.md new file mode 100644 index 0000000000..cb116b1a61 --- /dev/null +++ b/website/docs/contributing/ADRs/overarching/domain-language.md @@ -0,0 +1,24 @@ +--- +title: "ADR: Domain language" +--- + +## Background + +In the codebase, we have seen the need to define a domain language that we use to refer to features, methods to keep it consistent across the codebase. This ADR will contain a growing list of domain language used to keep the consistency across the codebase. + +## Decision + +We have decided to use the same domain language for the features we develop. Each feature will have it's own domain language to keep it consistent across the codebase. + +## Change requests domain language + +* *Change request*: An entity referring to the overarching data structure of a change request. A change request contains changes, and can be approved or rejected. +* *Change*: A term referring to a single change within a change request +* *Changes*: A term referring to a group of changes within a change request +* *Discard*: A term used for deleting a single change of a change request, or discarding an entire change request. +* *Pending*: A *pending* change request is one that has not yet been applied or discarded. In other words, it is in one of these three states: + 1. `Draft` + 2. `In review` + 3. `Approved` +* *Closed*: A *closed* change request has either been applied or cancelled and can no longer be changed. Change requests that are either `Applied` or `Cancelled` are considered closed. + diff --git a/website/docs/contributing/backend/overview.md b/website/docs/contributing/backend/overview.md index d971456e5e..b929dffb0b 100644 --- a/website/docs/contributing/backend/overview.md +++ b/website/docs/contributing/backend/overview.md @@ -8,8 +8,8 @@ The frontend is written in nodejs/typescript. It's written as a REST API followi We have created a set of ADRs to help guide the development of the backend: -* [Naming](./ADR/naming.md) -* [Preferred export](./ADR/preferred-export.md) +* [Naming](../ADRs/back-end/naming.md) +* [Preferred export](../ADRs/back-end/preferred-export.md) ## Requirements diff --git a/website/docs/contributing/frontend/overview.md b/website/docs/contributing/frontend/overview.md index 0dc59d58df..21555c65cf 100644 --- a/website/docs/contributing/frontend/overview.md +++ b/website/docs/contributing/frontend/overview.md @@ -10,14 +10,14 @@ The frontend is written in react/typescript. It's is a single page application t We have created a set of ADRs to help guide the development of the frontend: -* [Component naming](./ADR/component-naming.md) -* [Interface naming](./ADR/interface-naming.md) -* [Preferred component props usage](./ADR/preferred-component-props-usage.md) -* [Preferred export](./ADR/preferred-export.md) -* [Preferred function type](./ADR/preferred-function-type.md) -* [Preferred style import placement](./ADR/preferred-styles-import-placement.md) -* [Preferred styling method](./ADR/preferred-styling-method.md) -* [Preferred data mutation method](./ADR/preferred-data-mutation-method.md) -* [Preferred data fetching method](./ADR/preferred-data-fetching-method.md) -* [Preferred folder structure](./ADR/preferred-folder-structure.md) -* [Preferred form architecture](./ADR/preferred-form-architecture.md) +* [Component naming](../ADRs/front-end/component-naming.md) +* [Interface naming](../ADRs/front-end/interface-naming.md) +* [Preferred component props usage](../ADRs/front-end/preferred-component-props-usage.md) +* [Preferred export](../ADRs/front-end/preferred-export.md) +* [Preferred function type](../ADRs/front-end/preferred-function-type.md) +* [Preferred style import placement](../ADRs/front-end/preferred-styles-import-placement.md) +* [Preferred styling method](../ADRs/front-end/preferred-styling-method.md) +* [Preferred data mutation method](../ADRs/front-end/preferred-data-mutation-method.md) +* [Preferred data fetching method](../ADRs/front-end/preferred-data-fetching-method.md) +* [Preferred folder structure](../ADRs/front-end/preferred-folder-structure.md) +* [Preferred form architecture](../ADRs/front-end/preferred-form-architecture.md) diff --git a/website/sidebars.js b/website/sidebars.js index 05e991bc3d..4e693906db 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -341,5 +341,31 @@ module.exports = { }, ], }, + { + label: 'Developer contribution docs', + type: 'category', + collapsed: true, + link: { + type: 'generated-index', + title: 'Developer Guide', + description: 'Learn how to contribute to unleash.', + slug: '/developer-guide', + }, + items: [ + 'contributing/developer-guide', + 'contributing/frontend/overview', + 'contributing/backend/overview', + { + type: 'category', + label: 'Architectural Decision Records', + items: [ + { + type: 'autogenerated', + dirName: 'contributing/ADRs', // '.' means the current docs folder + }, + ], + }, + ], + }, ], };