opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2023-08-23 12:27:57 +03:00
committed by GitHub
parent ed2b1236c0
commit d37f6d80f7
96 changed files with 2838 additions and 1457 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contributing/CODE_OF_CONDUCT.md
+16 -15
View File
@@ -5,9 +5,9 @@
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.
size, disability, ethnicity, sex characteristics, gender identity and
expression, level of experience, education, socio-economic status, nationality,
personal appearance, race, religion, or sexual identity and orientation.
## Our Standards
@@ -37,11 +37,11 @@ Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
Project maintainers have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, or to ban temporarily or permanently any
contributor for other behaviors that they deem inappropriate, threatening,
offensive, or harmful.
## Scope
@@ -55,11 +55,11 @@ further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at opensource@coder.com. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
reported by contacting the project team at opensource@coder.com. All complaints
will be reviewed and investigated and will result in a response that is deemed
necessary and appropriate to the circumstances. The project team is obligated to
maintain confidentiality with regard to the reporter of an incident. Further
details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
@@ -67,8 +67,9 @@ members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 1.4, available at
https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
[homepage]: https://www.contributor-covenant.org
docs/contributing/SECURITY.md
+2 -2
View File
@@ -1,4 +1,4 @@
# Security Policy
If you find a vulnerability, **DO NOT FILE AN ISSUE**.
Instead, send an email to security@coder.com.
If you find a vulnerability, **DO NOT FILE AN ISSUE**. Instead, send an email to
security@coder.com.
docs/contributing/documentation.md
+16 -15
View File
@@ -10,12 +10,12 @@ This style guide is primarily for use with authoring documentation.
- Use plural nouns and pronouns (_they_, _their_, or _them_), especially when
the specific number is uncertain (i.e., "Set up your environments" even though
you don't know if the user will have one or many environments)
- When writing documentation titles, use the noun form, not the gerund form (e.g., "Environment
Management" instead of "Managing Environments")
- When writing documentation titles, use the noun form, not the gerund form
(e.g., "Environment Management" instead of "Managing Environments")
- Context matters when you decide whether to capitalize something or not. For
example, ["A Job creates one or more
Pods..."](https://kubernetes.io/docs/concepts/workloads/controllers/job/) is
correct when writing about Kubernetes. However, in other contexts, neither
example,
["A Job creates one or more Pods..."](https://kubernetes.io/docs/concepts/workloads/controllers/job/)
is correct when writing about Kubernetes. However, in other contexts, neither
_job_ nor _pods_ would be capitalized. Please follow the conventions set forth
by the relevant companies and open source communities.
@@ -79,8 +79,8 @@ For code that you want users to enter via a command-line interface, use
### Punctuation
Do not use the ampersand (&) as a shorthand for _and_ unless you're referring to a
UI element or the name of something that uses _&_.
Do not use the ampersand (&) as a shorthand for _and_ unless you're referring to
a UI element or the name of something that uses _&_.
You can use the symbol `~` in place of the word _approximately_.
@@ -91,13 +91,14 @@ and anything that has a name visible to the user, use bold font.
**Example:** On the **Environment Overview** page, click **Configure SSH**.
Don't use code font for UI elements unless it is rendered based on previously entered
text. For example, if you tell the user to provide the environment name as
`myEnvironment`, then use both bold and cold font when referring to the name.
Don't use code font for UI elements unless it is rendered based on previously
entered text. For example, if you tell the user to provide the environment name
as `myEnvironment`, then use both bold and cold font when referring to the name.
**Example**: Click **`myEnvironment`**.
When writing out instructions that involve UI elements, both of the following options are acceptable:
When writing out instructions that involve UI elements, both of the following
options are acceptable:
- Go to **Manage** > **Users**.
- In the **Manage** menu, click **Users**.
@@ -111,13 +112,13 @@ Below summarizes the guidelines regarding how Coder terms should be used.
The only Coder-specific terms that should be capitalized are the names of
products (e.g., Coder).
The exception is **code-server**, which is always lowercase. If it appears at the
beginning of the sentence, rewrite the sentence to avoid this usage.
The exception is **code-server**, which is always lowercase. If it appears at
the beginning of the sentence, rewrite the sentence to avoid this usage.
### Uncapitalized terms
In general, we do not capitalize the names of features (unless the situation calls for it,
such as the word appearing at the beginning of a sentence):
In general, we do not capitalize the names of features (unless the situation
calls for it, such as the word appearing at the beginning of a sentence):
- account dormancy
- audit logs
docs/contributing/feature-stages.md
+10 -4
View File
@@ -4,13 +4,18 @@ Some Coder features are released as Alpha or Experimental.
## Alpha features
Alpha features are enabled in all Coder deployments but the feature is subject to change, or even be removed. Breaking changes may not be documented in the changelog. In most cases, features will only stay in alpha for 1 month.
Alpha features are enabled in all Coder deployments but the feature is subject
to change, or even be removed. Breaking changes may not be documented in the
changelog. In most cases, features will only stay in alpha for 1 month.
We recommend using [GitHub issues](https://github.com/coder/coder/issues) to leave feedback and get support for alpha features.
We recommend using [GitHub issues](https://github.com/coder/coder/issues) to
leave feedback and get support for alpha features.
## Experimental features
These features are disabled by default, and not recommended for use in production as they may cause performance or stability issues. In most cases, features will only stay in experimental for 1-2 weeks of internal testing.
These features are disabled by default, and not recommended for use in
production as they may cause performance or stability issues. In most cases,
features will only stay in experimental for 1-2 weeks of internal testing.
```yaml
# Enable all experimental features
@@ -22,4 +27,5 @@ coder server --experiments=feature1,feature2
# Alternatively, use the `CODER_EXPERIMENTS` environment variable.
```
For a list of all experiments, refer to the [codersdk reference](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#Experiment).
For a list of all experiments, refer to the
[codersdk reference](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#Experiment).
docs/contributing/frontend.md
+121 -35
View File
@@ -1,36 +1,51 @@
# Frontend
This is a guide to help the Coder community and also Coder members contribute to our UI. It is ongoing work but we hope it provides some useful information to get started. If you have any questions or need help, please send us a message on our [Discord server](https://discord.com/invite/coder). We'll be happy to help you.
This is a guide to help the Coder community and also Coder members contribute to
our UI. It is ongoing work but we hope it provides some useful information to
get started. If you have any questions or need help, please send us a message on
our [Discord server](https://discord.com/invite/coder). We'll be happy to help
you.
## Running the UI
You can run the UI and access the dashboard in two ways:
- Build the UI pointing to an external Coder server: `CODER_HOST=https://mycoder.com pnpm dev` inside of the `site` folder. This is helpful when you are building something in the UI and already have the data on your deployed server.
- Build the entire Coder server + UI locally: `./scripts/develop.sh` in the root folder. It is useful when you have to contribute with features that are not deployed yet or when you have to work on both, frontend and backend.
- Build the UI pointing to an external Coder server:
`CODER_HOST=https://mycoder.com pnpm dev` inside of the `site` folder. This is
helpful when you are building something in the UI and already have the data on
your deployed server.
- Build the entire Coder server + UI locally: `./scripts/develop.sh` in the root
folder. It is useful when you have to contribute with features that are not
deployed yet or when you have to work on both, frontend and backend.
In both cases, you can access the dashboard on `http://localhost:8080`. If you are running the `./scripts/develop.sh` you can log in using the default credentials: `admin@coder.com` and `SomeSecurePassword!`.
In both cases, you can access the dashboard on `http://localhost:8080`. If you
are running the `./scripts/develop.sh` you can log in using the default
credentials: `admin@coder.com` and `SomeSecurePassword!`.
## Tech Stack
All our dependencies are described in `site/package.json` but here are the most important ones:
All our dependencies are described in `site/package.json` but here are the most
important ones:
- [React](https://reactjs.org/) as framework
- [Typescript](https://www.typescriptlang.org/) to keep our sanity
- [Vite](https://vitejs.dev/) to build the project
- [Material V5](https://mui.com/material-ui/getting-started/) for UI components
- [react-router](https://reactrouter.com/en/main) for routing
- [TanStack Query v4](https://tanstack.com/query/v4/docs/react/overview) for fetching data
- [TanStack Query v4](https://tanstack.com/query/v4/docs/react/overview) for
fetching data
- [XState](https://xstate.js.org/docs/) for handling complex state flows
- [axios](https://github.com/axios/axios) as fetching lib
- [Playwright](https://playwright.dev/) for E2E testing
- [Jest](https://jestjs.io/) for integration testing
- [Storybook](https://storybook.js.org/) and [Chromatic](https://www.chromatic.com/) for visual testing
- [Storybook](https://storybook.js.org/) and
[Chromatic](https://www.chromatic.com/) for visual testing
- [PNPM](https://pnpm.io/) as package manager
## Structure
All the code related to the UI is inside the `site` folder and we defined a few conventions to help people to navigate through it.
All the code related to the UI is inside the `site` folder and we defined a few
conventions to help people to navigate through it.
- **e2e** - E2E tests
- **src** - Source code
@@ -43,38 +58,69 @@ All the code related to the UI is inside the `site` folder and we defined a few
- **pages** - Page components
- **testHelpers** - Helper functions to help with integration tests
- **util** - Helper functions that can be used across the application
- **xServices** - XState machines used to fetch data and handle complex scenarios
- **xServices** - XState machines used to fetch data and handle complex
scenarios
- **static** - UI static assets like images, fonts, icons, etc
## Routing
We use [react-router](https://reactrouter.com/en/main) as our routing engine and adding a new route is very easy. If the new route needs to be authenticated, put it under the `<RequireAuth>` route and if it needs to live inside of the dashboard, put it under the `<DashboardLayout>` route.
We use [react-router](https://reactrouter.com/en/main) as our routing engine and
adding a new route is very easy. If the new route needs to be authenticated, put
it under the `<RequireAuth>` route and if it needs to live inside of the
dashboard, put it under the `<DashboardLayout>` route.
The `RequireAuth` component handles all the authentication logic for the routes and the `DashboardLayout` wraps the route adding a navbar and passing down common dashboard data.
The `RequireAuth` component handles all the authentication logic for the routes
and the `DashboardLayout` wraps the route adding a navbar and passing down
common dashboard data.
## Pages
Pages are the top-level components of the app. The page component lives under the `src/pages` folder and each page should have its own folder so we can better group the views, tests, utility functions and so on. We use a structure where the page component is responsible for fetching all the data and passing it down to the view. We explain this decision a bit better in the next section.
Pages are the top-level components of the app. The page component lives under
the `src/pages` folder and each page should have its own folder so we can better
group the views, tests, utility functions and so on. We use a structure where
the page component is responsible for fetching all the data and passing it down
to the view. We explain this decision a bit better in the next section.
> ℹ️ Code that is only related to the page should live inside of the page folder but if at some point it is used in other pages or components, you should consider moving it to the `src` level in the `utils`, `hooks` or `components` folder.
> ℹ️ Code that is only related to the page should live inside of the page folder
> but if at some point it is used in other pages or components, you should
> consider moving it to the `src` level in the `utils`, `hooks` or `components`
> folder.
### States
A page usually has at least three states: **loading**, **ready** or **success**, and **error** so remember to always handle these scenarios while you are coding a page. We also encourage you to add visual testing for these three states using the `*.stories.ts` file.
A page usually has at least three states: **loading**, **ready** or **success**,
and **error** so remember to always handle these scenarios while you are coding
a page. We also encourage you to add visual testing for these three states using
the `*.stories.ts` file.
## Fetching data
We use [TanStack Query v4](https://tanstack.com/query/v4/docs/react/overview)(previously known as react-query) to fetch data from the API. We also use [XState](https://xstate.js.org/docs/) to handle complex flows with multiple states and transitions.
We use
[TanStack Query v4](https://tanstack.com/query/v4/docs/react/overview)(previously
known as react-query) to fetch data from the API. We also use
[XState](https://xstate.js.org/docs/) to handle complex flows with multiple
states and transitions.
> ℹ️ We recently changed how we are going to fetch data from the server so you will see a lot of fetches being made using XState machines but feel free to refactor it if you are already touching those files.
> ℹ️ We recently changed how we are going to fetch data from the server so you
> will see a lot of fetches being made using XState machines but feel free to
> refactor it if you are already touching those files.
### Where to fetch data
Finding the right place to fetch data in React apps is the one million dollar question but we decided to make it only in the page components and pass the props down to the views. This makes it easier to find where data is being loaded and easy to test using Storybook. So you will see components like `UsersPage` and `UsersPageView`.
Finding the right place to fetch data in React apps is the one million dollar
question but we decided to make it only in the page components and pass the
props down to the views. This makes it easier to find where data is being loaded
and easy to test using Storybook. So you will see components like `UsersPage`
and `UsersPageView`.
### API
We are using [axios](https://github.com/axios/axios) as our fetching library and writing the API functions in the `site/src/api/api.ts` files. We also have auto-generated types from our Go server on `site/src/api/typesGenerated.ts`. Usually, every endpoint has its own ` Request` and `Response` types but sometimes you need to pass extra parameters to make the call like the example below:
We are using [axios](https://github.com/axios/axios) as our fetching library and
writing the API functions in the `site/src/api/api.ts` files. We also have
auto-generated types from our Go server on `site/src/api/typesGenerated.ts`.
Usually, every endpoint has its own ` Request` and `Response` types but
sometimes you need to pass extra parameters to make the call like the example
below:
```ts
export const getAgentListeningPorts = async (
@@ -87,7 +133,8 @@ export const getAgentListeningPorts = async (
}
```
Sometimes, a FE operation can have multiple API calls so it is ok to wrap it as a single function.
Sometimes, a FE operation can have multiple API calls so it is ok to wrap it as
a single function.
```ts
export const updateWorkspaceVersion = async (
@@ -98,45 +145,73 @@ export const updateWorkspaceVersion = async (
}
```
If you need more granular errors or control, you may should consider keep them separated and use XState for that.
If you need more granular errors or control, you may should consider keep them
separated and use XState for that.
## Components
We are using [Material V4](https://v4.mui.com/) in our UI and we don't have any short-term plans to update or even replace it. It still provides good value for us and changing it would cost too much work which is not valuable right now but of course, it can change in the future.
We are using [Material V4](https://v4.mui.com/) in our UI and we don't have any
short-term plans to update or even replace it. It still provides good value for
us and changing it would cost too much work which is not valuable right now but
of course, it can change in the future.
### Structure
Each component gets its own folder. Make sure you add a test and Storybook stories for the component as well. By keeping these tidy, the codebase will remain easy to navigate, healthy and maintainable for all contributors.
Each component gets its own folder. Make sure you add a test and Storybook
stories for the component as well. By keeping these tidy, the codebase will
remain easy to navigate, healthy and maintainable for all contributors.
### Accessibility
We strive to keep our UI accessible. When using colors, avoid adding new elements with low color contrast. Always use labels on inputs, not just placeholders. These are important for screen-readers.
We strive to keep our UI accessible. When using colors, avoid adding new
elements with low color contrast. Always use labels on inputs, not just
placeholders. These are important for screen-readers.
### Should I create a new component?
As with most things in the world, it depends. If you are creating a new component to encapsulate some UI abstraction like `UsersTable` it is ok but you should always try to use the base components that are provided by the library or from the codebase so I recommend you to always do a quick search before creating a custom primitive component like dialogs, popovers, buttons, etc.
As with most things in the world, it depends. If you are creating a new
component to encapsulate some UI abstraction like `UsersTable` it is ok but you
should always try to use the base components that are provided by the library or
from the codebase so I recommend you to always do a quick search before creating
a custom primitive component like dialogs, popovers, buttons, etc.
## Testing
We use three types of testing in our app: **E2E**, **Integration** and **Visual Testing**.
We use three types of testing in our app: **E2E**, **Integration** and **Visual
Testing**.
### E2E (end-to-end)
Are useful to test complete flows like "Create a user", "Import template", etc. For this one, we use [Playwright](https://playwright.dev/). If you only need to test if the page is being rendered correctly, you should probably consider using the **Visual Testing** approach.
Are useful to test complete flows like "Create a user", "Import template", etc.
For this one, we use [Playwright](https://playwright.dev/). If you only need to
test if the page is being rendered correctly, you should probably consider using
the **Visual Testing** approach.
> ℹ️ For scenarios where you need to be authenticated, you can use `test.use({ storageState: getStatePath("authState") })`.
> ℹ️ For scenarios where you need to be authenticated, you can use
> `test.use({ storageState: getStatePath("authState") })`.
### Integration
Test user interactions like "Click in a button shows a dialog", "Submit the form sends the correct data", etc. For this, we use [Jest](https://jestjs.io/) and [react-testing-library](https://testing-library.com/docs/react-testing-library/intro/). If the test involves routing checks like redirects or maybe checking the info on another page, you should probably consider using the **E2E** approach.
Test user interactions like "Click in a button shows a dialog", "Submit the form
sends the correct data", etc. For this, we use [Jest](https://jestjs.io/) and
[react-testing-library](https://testing-library.com/docs/react-testing-library/intro/).
If the test involves routing checks like redirects or maybe checking the info on
another page, you should probably consider using the **E2E** approach.
### Visual testing
Test components without user interaction like testing if a page view is rendered correctly depending on some parameters, if the button is showing a spinner if the `loading` props are passing, etc. This should always be your first option since it is way easier to maintain. For this, we use [Storybook](https://storybook.js.org/) and [Chromatic](https://www.chromatic.com/).
Test components without user interaction like testing if a page view is rendered
correctly depending on some parameters, if the button is showing a spinner if
the `loading` props are passing, etc. This should always be your first option
since it is way easier to maintain. For this, we use
[Storybook](https://storybook.js.org/) and
[Chromatic](https://www.chromatic.com/).
### What should I test?
Choosing what to test is not always easy since there are a lot of flows and a lot of things can happen but these are a few indicators that can help you with that:
Choosing what to test is not always easy since there are a lot of flows and a
lot of things can happen but these are a few indicators that can help you with
that:
- Things that can block the user
- Reported bugs
@@ -144,18 +219,27 @@ Choosing what to test is not always easy since there are a lot of flows and a lo
### Tests getting too slow
A few times you can notice tests can take a very long time to get done. Sometimes it is because the test itself is complex and runs a lot of stuff, and sometimes it is because of how we are querying things. In the next section, we are going to talk more about them.
A few times you can notice tests can take a very long time to get done.
Sometimes it is because the test itself is complex and runs a lot of stuff, and
sometimes it is because of how we are querying things. In the next section, we
are going to talk more about them.
#### Using `ByRole` queries
One thing we figured out that was slowing down our tests was the use of `ByRole` queries because of how it calculates the role attribute for every element on the `screen`. You can read more about it on the links below:
One thing we figured out that was slowing down our tests was the use of `ByRole`
queries because of how it calculates the role attribute for every element on the
`screen`. You can read more about it on the links below:
- https://stackoverflow.com/questions/69711888/react-testing-library-getbyrole-is-performing-extremely-slowly
- https://github.com/testing-library/dom-testing-library/issues/552#issuecomment-625172052
Even with `ByRole` having performance issues we still want to use it but for that, we have to scope the "querying" area by using the `within` command. So instead of using `screen.getByRole("button")` directly we could do `within(form).getByRole("button")`.
Even with `ByRole` having performance issues we still want to use it but for
that, we have to scope the "querying" area by using the `within` command. So
instead of using `screen.getByRole("button")` directly we could do
`within(form).getByRole("button")`.
❌ Not ideal. If the screen has a hundred or thousand elements it can be VERY slow.
❌ Not ideal. If the screen has a hundred or thousand elements it can be VERY
slow.
```tsx
user.click(screen.getByRole("button"))
@@ -170,7 +254,9 @@ user.click(within(form).getByRole("button"))
#### `jest.spyOn` with the API is not working
For some unknown reason, we figured out the `jest.spyOn` is not able to mock the API function when they are passed directly into the services XState machine configuration.
For some unknown reason, we figured out the `jest.spyOn` is not able to mock the
API function when they are passed directly into the services XState machine
configuration.
❌ Does not work