Skip to content

Commit

Permalink
docs: Move 'project conventions' from HACKING.md to MAASUI.md MAASENG…
Browse files Browse the repository at this point in the history
…-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)
  • Loading branch information
ndv99 authored Aug 21, 2024
1 parent e190f73 commit 1603d1b
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 40 deletions.
37 changes: 0 additions & 37 deletions docs/HACKING.md
Original file line number Diff line number Diff line change
@@ -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)
Expand Down Expand Up @@ -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.**
Expand Down
35 changes: 32 additions & 3 deletions docs/MAASUI.md
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit 1603d1b

Please sign in to comment.