From 1603d1b780f067146e0320c5f686bedb20700b43 Mon Sep 17 00:00:00 2001
From: Nick De Villiers <nick.devilliers@canonical.com>
Date: Wed, 21 Aug 2024 12:56:39 +0100
Subject: [PATCH] docs: Move 'project conventions' from HACKING.md to MAASUI.md
 MAASENG-3602 (#5525)

- Moved the "Project conventions" section out of HACKING.md and into MAASUI.md
- Moved "Usability" section to within "Project conventions"
- Moved TypeScript section in Project Conventions to existing "TypeScript" heading
  - Removed redundant paragraph on `TSFixMe` type

Resolves [MAASENG-3602](https://warthogs.atlassian.net/browse/MAASENG-3602)
---
 docs/HACKING.md | 37 -------------------------------------
 docs/MAASUI.md  | 35 ++++++++++++++++++++++++++++++++---
 2 files changed, 32 insertions(+), 40 deletions(-)

diff --git a/docs/HACKING.md b/docs/HACKING.md
index 0c195bdcad..74a0949cf5 100644
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -1,10 +1,5 @@
 # Hacking
 
--   [Project conventions](#project-conventions)
-    -   [TypeScript](#typescript)
-    -   [Code style](#code-style)
-    -   [React Components](#react-components)
-        -   [Dealing with problems](#dealing-with-problems)
 -   [Development setup](#development-setup)
     -   [Run MAAS-UI on your local machine](#run-maas-ui-on-your-local-machine)
         -   [Setup MAAS-UI, node and yarn](#setup-maas-ui-node-and-yarn)
@@ -44,38 +39,6 @@
 -   [Show intro](#show-intro)
 -   [Sample data](#sample-data)
 
-# Project conventions
-
-## TypeScript
-
-maas-ui built with TypeScript in strict mode. Any new modules in should be written in [TypeScript](https://www.typescriptlang.org/).
-
-## Code style
-
-Prioritize clear, self-explanatory code, and only use JSDoc to provide context or additional information that cannot be inferred from the code itself.
-
-## React Components
-
-We encourage [component-driven](https://www.componentdriven.org/) development, and use of [Storybook](https://storybook.js.org/) for interactive documentation.
-
-Follow the presentational and container components pattern where appropriate. Read more on good component design in the  [React documentation](https://reactjs.org/docs/thinking-in-react.html#step-3-identify-the-minimal-but-complete-representation-of-ui-state).
-
-When developing new features or extending existing ones, consider the following:
-
-- Think of all the variations of a UI component and how each can be represented using props.
-- Prefer a single `variant` prop for representing visual variations of a component.
-
-```tsx
-<Button variant="primary" />
-```
-
-- Create stories for each variant in [Storybook](https://storybook.js.org/).
-- Add state management, side effects, and application-specific logic into container component passing the state as props to the presentational component.
-
-### Dealing with problems
-
-There are cases where determining a type for a particular object can be difficult. We provide an "escape hatch" type called `TSFixMe` (aliased to `any`) which you can use, but please make a best effort to avoid this and determine the correct types where possible.
-
 # Development setup
 
 **Note: You will need access to a running instance of MAAS in order to run maas-ui.**
diff --git a/docs/MAASUI.md b/docs/MAASUI.md
index 5d63a5e9b3..2073a6c635 100644
--- a/docs/MAASUI.md
+++ b/docs/MAASUI.md
@@ -1,8 +1,11 @@
 # MAAS UI
 
-## Content
+## Contents
 
-- [Usability](#usability)
+- [Project conventions](#project-conventions)
+  - [Usability](#usability)
+  - [Code style](#code-style)
+  - [React components](#react-components)
 - [Code structure](#code-structure)
 - [React](#react)
   - [Hooks](#hooks)
@@ -26,11 +29,35 @@
   - [Cypress](#cypress)
   - [Playwright](#playwright)
 
-## Usability
+## Project conventions
+
+### Usability
 
 Our unofficial policy on responsive design in MAAS-UI is that everything should be clearly visible on all screen sizes, but it doesn't necessarily have to be the most visually appealing on small screens.
 Only a small percentage of users interact with the MAAS client on mobile devices, but it's not uncommon for people to use it on one half of their monitor viewport.
 
+### Code style
+
+Prioritize clear, self-explanatory code, and only use JSDoc to provide context or additional information that cannot be inferred from the code itself.
+
+### React Components
+
+We encourage [component-driven](https://www.componentdriven.org/) development, and use of [Storybook](https://storybook.js.org/) for interactive documentation.
+
+Follow the presentational and container components pattern where appropriate. Read more on good component design in the  [React documentation](https://reactjs.org/docs/thinking-in-react.html#step-3-identify-the-minimal-but-complete-representation-of-ui-state).
+
+When developing new features or extending existing ones, consider the following:
+
+- Think of all the variations of a UI component and how each can be represented using props.
+- Prefer a single `variant` prop for representing visual variations of a component.
+
+```tsx
+<Button variant="primary" />
+```
+
+- Create stories for each variant in [Storybook](https://storybook.js.org/).
+- Add state management, side effects, and application-specific logic into container component passing the state as props to the presentational component.
+
 ## Code structure
 
 The high-level interactions between the React side of the frontend and the API are illustrated below.
@@ -173,6 +200,8 @@ The `sendMessage` function handles sending WebSocket messages. It first dispatch
 
 ### TypeScript
 
+maas-ui built with TypeScript in strict mode. Any new modules in should be written in [TypeScript](https://www.typescriptlang.org/).
+
 #### TSFixMe
 
 There may occasionally be times where you can’t type something. In those cases you might be able to use \`any\` to handle all types. However, our linter will not let you use \`any\` directly.