TiDB Cloud Management Portal UI
[](https://app.netlify.com/sites/management-portal/deploys)
A Web UI for TiDB Cloud Management Portal. Powered by ⚛️ [Create React App](https://github.com/facebook/create-react-app) and [TypeScript](https://www.typescriptlang.org/).
You can learn more in the [Create React App with TypScript documentation](https://create-react-app.dev/docs/adding-typescript/).
To learn React, check out the [React documentation](https://reactjs.org/).
## Getting Started
First, you need to ensure that there is a TiDB Cloud Management Portal server proxy available to provide API services (which can refer to [dbaas](https://github.com/pingcap/dbaas) README).
Then, clone a copy of this repo:
```sh
git clone https://github.com/tidbcloud/management-portal-ui.git && cd management-portal-ui
```
> Note: you should make sure [Node](https://nodejs.org/en/) is installed.
Check the node version:
```sh
node -v
# v13.7.0 is the node version we currently use for development
```
add the file `.env` with the `domain` and `clientId` of the auth0 application and the `serviceUrl` of the DBaaS endpoint(optional):
```sh
REACT_APP_AUTH0_DOMAIN='your_domain'
REACT_APP_AUTH0_CLIENT_ID='your_client_id'
REACT_APP_SERVICE_URL='your DBaaS server endpoint' // 'https://us-west-2.nightly.shared.aws.tidbcloud.com' (default)
REACT_APP_DEVOPS_ADDR='your DevOps server endpoint' // 'https://dev.devops.pingcap.com' (default)
```
and run:
> Note: you should run `yarn run gen:api` to generate api files before you start development. For more information about `yarn run gen:api`, please refer to the next section [Contributing and Developing](#contributing-and-developing)
```sh
yarn && yarn run gen:api && yarn start
```
> Note: you should install [yarn](https://classic.yarnpkg.com/en/docs/install#mac-stable) as the package manager (recommended).
or run:
```sh
npm install && npm run gen:api && npm start
```
Your browser will open automatically to show the TiDB Cloud entry page by default.
## Contributing and Developing
For better collaboration and review, we have developed a few rules to help us develop better.
For developing UI logic with OpenAPI, you should check whether the `./swagger.json` in this repository is consistent with the file exported from the backend (`{REACT_APP_SERVICE_URL}/openapi-ui/swagger.json?jwt={AUTH_TOKEN}`), and then run the following script to generate the corresponding api files in `src/apiClient/openapi`:
```sh
yarn run gen:api
```
or
```sh
npm run gen:api
```
### TS or JS
Because we chose vscode as the IDE to develop dashboard, we recommend using the [prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extension to format our code.
### Theme and Styles
We use [Ant Design](https://ant.design/) as our UI library, and use [Less](http://lesscss.org/) to do some custom styling stuff according to the document of [Customize Theme](https://ant.design/docs/react/customize-theme) recommended by antd.
### Git-flow
Generally, we use the `master` branch as the production branch (corresponding to deployments of [ops.tidbcloud.com](https://ops.tidbcloud.com) and [ops-staging.tidbcloud.com](https://ops-staging.tidbcloud.com), where the staging environment is used as the test and verification environment before release), and the `dev` branch as the development branch (corresponding to the deployment of [ops-dev.tidbcloud.com](https://ops-dev.tidbcloud.com)).
In periodic iterative development, each new feature development or bug fix needs to checkout a new branch from the `dev` branch to submit commits, and then merge commits into the `dev` branch by a Pull Request (this will trigger the deploy hook of the dev environment in Netlify).
For every release, you need to checkout a new `release` branch to pick relevant commits and create a Pull Request to `master` branch (the deploy hook of the staging environment in Netlify will be triggered after the PR is merged). After the verification and testing of the staging environment are completed, the administrator needs to manually publish the release to the production environment.
> Note: After each release is launched, please reset the `dev` branch to be consistent with the `master` branch, and **DELETE** the `release` branch and other merged branches in time
If there is an urgent hotfix, you can directly check out a `hotfix` branch from the `master` to fix it.
### Branch Naming
The naming convention of branches is `{prefix}/{description}`
- **feat**: features development such as feat/rbac
- **fix**, **hotfix**: bug fix, such as fix/billing-status, hotfix/typos
- **refine**, **polish**: UI polish or refine of logic implementation, such as polish/table-pagination, refine/api-client
- **chore**, **docs** and other cases, such as chore/readme, docs/overview
- **release-[date]**: release branch such as release-20201125
#### Commit Message
We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as a unified writing specification for commit messages.
#### PR Writing Specification
- What problem does this PR solve (related issues)?
- What is changed and how does it work?
- Checklist
- Does this PR introduce a UI change? (screen shots）
### CI/CD
- [ ] Documentations Improvement (use docz or storybook)
- [ ] Download swagger.json of OpenAPI from remote (need JWT authentication)
- [ ] Run test in CI
- [ ] Lint code format in CI
## Performance Improvement
For analyzing the bundle size, you can run the following script after building.
```sh
yarn run analyze
```
Then you can watch the bundle size treemap by visiting [http://localhost:8888](http://localhost:8888) .
## Authors
Originally designed by PingCAP TiDB Cloud Team.