uptime-kuma/CONTRIBUTING.md

238 lines
6.2 KiB
Markdown
Raw Normal View History

# Project Info
2021-11-17 06:09:12 +00:00
First of all, thank you everyone who made pull requests for Uptime Kuma, I never thought GitHub Community can be that nice! And also because of this, I also never thought other people actually read my code and edit my code. It is not structured and commented so well, lol. Sorry about that.
2021-12-02 10:15:14 +00:00
The project was created with vite.js (vue3). Then I created a subdirectory called "server" for server part. Both frontend and backend share the same package.json.
2021-10-03 09:04:16 +01:00
The frontend code build into "dist" directory. The server (express.js) exposes the "dist" directory as root of the endpoint. This is how production is working.
2021-10-13 01:01:34 +01:00
## Key Technical Skills
2021-10-03 09:04:16 +01:00
- Node.js (You should know what are promise, async/await and arrow function etc.)
- Socket.io
- SCSS
- Vue.js
- Bootstrap
- SQLite
2021-10-13 01:01:34 +01:00
## Directories
2021-10-03 09:04:16 +01:00
- data (App data)
- dist (Frontend build)
- extra (Extra useful scripts)
- public (Frontend resources for dev only)
- server (Server source code)
- src (Frontend source code)
- test (unit test)
2021-10-13 01:01:34 +01:00
## Can I create a pull request for Uptime Kuma?
2021-08-24 07:42:35 +01:00
2022-03-02 06:25:37 +00:00
⚠️ 2022-03-02 Update:
2021-08-24 07:42:35 +01:00
2022-03-02 06:25:37 +00:00
Since I found that merging pull requests is a pretty heavy task for me, I try to rearrange it.
✅ Accept:
- Bug/Security fix
- Translations
- Adding notification providers
❌ Avoid:
- Large pull requests
- New big features
My long story here: https://www.reddit.com/r/UptimeKuma/comments/t1t6or/comment/hynyijx/
2021-10-25 05:06:01 +01:00
### Recommended Pull Request Guideline
1. Fork the project
1. Clone your fork repo to local
1. Create a new branch
1. Create an empty commit
`git commit -m "[empty commit] pull request for <YOUR TASK NAME>" --allow-empty`
1. Push to your fork repo
2021-10-26 04:28:38 +01:00
1. Create a pull request: https://github.com/louislam/uptime-kuma/compare
2021-12-02 10:15:14 +00:00
1. Write a proper description
2021-10-25 05:06:01 +01:00
1. Click "Change to draft"
2021-08-24 07:42:35 +01:00
2021-10-13 01:01:34 +01:00
#### ❌ Won't Merge
2021-08-24 07:42:35 +01:00
2021-10-25 05:06:01 +01:00
- Any breaking changes
2021-08-24 07:42:35 +01:00
- Duplicated pull request
- Buggy
- Existing logic is completely modified or deleted
- A function that is completely out of scope
2021-10-13 01:01:34 +01:00
## Project Styles
I personally do not like something need to learn so much and need to config so much before you can finally start the app.
- Easy to install for non-Docker users, no native build dependency is needed (at least for x86_64), no extra config, no extra effort to get it run
2021-10-10 07:40:19 +01:00
- Single container for Docker users, no very complex docker-compose file. Just map the volume and expose the port, then good to go
2021-10-03 09:04:16 +01:00
- Settings should be configurable in the frontend. Env var is not encouraged.
- Easy to use
2021-10-13 01:01:34 +01:00
## Coding Styles
2021-08-24 07:06:23 +01:00
2021-10-03 09:04:16 +01:00
- 4 spaces indentation
- Follow `.editorconfig`
- Follow ESLint
2021-08-24 07:06:23 +01:00
2021-10-13 01:01:34 +01:00
## Name convention
2021-08-24 07:06:23 +01:00
- Javascript/Typescript: camelCaseType
- SQLite: underscore_type
- CSS/SCSS: dash-type
2021-10-13 01:01:34 +01:00
## Tools
- Node.js >= 14
- Git
2021-11-17 06:09:12 +00:00
- IDE that supports ESLint and EditorConfig (I am using IntelliJ IDEA)
2021-10-03 09:04:16 +01:00
- A SQLite tool (SQLite Expert Personal is suggested)
2021-10-13 01:01:34 +01:00
## Install dependencies
```bash
2021-10-03 09:04:16 +01:00
npm ci
2021-08-31 13:36:17 +01:00
```
2021-10-13 01:01:34 +01:00
## How to start the Backend Dev Server
2021-09-23 15:48:19 +01:00
(2021-09-23 Update)
2021-09-23 15:48:19 +01:00
```bash
npm run start-server-dev
```
It binds to `0.0.0.0:3001` by default.
2021-10-13 01:01:34 +01:00
### Backend Details
It is mainly a socket.io app + express.js.
express.js is just used for serving the frontend built files (index.html, .js and .css etc.)
2021-10-03 09:04:16 +01:00
- model/ (Object model, auto mapping to the database table name)
- modules/ (Modified 3rd-party modules)
2021-11-17 06:09:12 +00:00
- notification-providers/ (individual notification logic)
2021-10-03 09:04:16 +01:00
- routers/ (Express Routers)
2021-12-02 10:15:14 +00:00
- socket-handler (Socket.io Handlers)
2021-10-03 09:04:16 +01:00
- server.js (Server main logic)
2021-10-13 01:01:34 +01:00
## How to start the Frontend Dev Server
2021-10-03 09:04:16 +01:00
1. Set the env var `NODE_ENV` to "development".
2021-10-05 01:44:50 +01:00
2. Start the frontend dev server by the following command.
2021-10-13 01:01:34 +01:00
2021-10-03 09:04:16 +01:00
```bash
npm run dev
```
2021-10-13 01:01:34 +01:00
2021-10-03 09:04:16 +01:00
It binds to `0.0.0.0:3000` by default.
You can use Vue.js devtools Chrome extension for debugging.
2021-10-13 01:01:34 +01:00
### Build the frontend
```bash
npm run build
```
2021-10-13 01:01:34 +01:00
### Frontend Details
Uptime Kuma Frontend is a single page application (SPA). Most paths are handled by Vue Router.
The router is in `src/router.js`
As you can see, most data in frontend is stored in root level, even though you changed the current router to any other pages.
The data and socket logic are in `src/mixins/socket.js`.
2021-10-13 01:01:34 +01:00
## Database Migration
2021-10-03 09:04:16 +01:00
1. Create `patch-{name}.sql` in `./db/`
2. Add your patch filename in the `patchList` list in `./server/database.js`
2021-10-13 01:01:34 +01:00
## Unit Test
2021-10-05 13:27:43 +01:00
It is an end-to-end testing. It is using Jest and Puppeteer.
2021-10-05 11:17:54 +01:00
2021-10-13 01:01:34 +01:00
```bash
2021-10-05 13:27:43 +01:00
npm run build
npm test
```
By default, the Chromium window will be shown up during the test. Specifying `HEADLESS_TEST=1` for terminal environments.
2021-10-05 11:17:54 +01:00
2021-10-13 01:01:34 +01:00
## Update Dependencies
2021-10-05 11:17:54 +01:00
Install `ncu`
https://github.com/raineorshine/npm-check-updates
```bash
ncu -u -t patch
npm install
```
2021-12-02 10:15:14 +00:00
Since previously updating Vite 2.5.10 to 2.6.0 broke the application completely, from now on, it should update patch release version only.
2021-10-05 11:17:54 +01:00
2021-10-13 01:01:34 +01:00
Patch release = the third digit ([Semantic Versioning](https://semver.org/))
2021-10-06 08:36:45 +01:00
2021-10-13 01:01:34 +01:00
## Translations
2021-10-06 08:36:45 +01:00
Please read: https://github.com/louislam/uptime-kuma/tree/master/src/languages
2021-10-20 17:03:55 +01:00
2021-10-26 16:56:14 +01:00
## Wiki
2021-12-02 10:15:14 +00:00
Since there is no way to make a pull request to wiki's repo, I have set up another repo to do that.
2021-10-26 16:56:14 +01:00
2021-10-26 17:02:20 +01:00
https://github.com/louislam/uptime-kuma-wiki
2021-10-26 16:56:14 +01:00
2021-12-02 10:15:14 +00:00
## Maintainer
2021-10-20 17:03:55 +01:00
2021-10-20 17:08:46 +01:00
Check the latest issues and pull requests:
2021-10-20 17:03:55 +01:00
https://github.com/louislam/uptime-kuma/issues?q=sort%3Aupdated-desc
### Release Procedures
2021-12-02 10:15:14 +00:00
2021-10-20 17:03:55 +01:00
1. Draft a release note
2022-03-22 08:45:07 +00:00
2. Make sure the repo is cleared
3. `npm run release-final with env vars: `VERSION` and `GITHUB_TOKEN`
4. Wait until the `Press any key to continue`
5. `git push`
6. Publish the release note as 1.X.X
7. Press any key to continue
8. SSH to demo site server and update to 1.X.X
2021-10-20 17:08:46 +01:00
Checking:
2021-12-02 10:15:14 +00:00
2021-10-20 17:08:46 +01:00
- Check all tags is fine on https://hub.docker.com/r/louislam/uptime-kuma/tags
- Try the Docker image with tag 1.X.X (Clean install / amd64 / arm64 / armv7)
2021-12-02 10:15:14 +00:00
- Try clean installation with Node.js
2021-10-26 16:56:14 +01:00
2022-03-20 03:08:33 +00:00
### Release Beta Procedures
1. Draft a release note, check "This is a pre-release"
2. Make sure the repo is cleared
3. `npm run release-beta` with env vars: `VERSION` and `GITHUB_TOKEN`
2022-03-22 08:45:07 +00:00
4. Wait until the `Press any key to continue`
2022-03-20 03:08:33 +00:00
5. Publish the release note as 1.X.X-beta.X
6. Press any key to continue
2021-10-26 16:56:14 +01:00
### Release Wiki
#### Setup Repo
2021-12-02 10:15:14 +00:00
```bash
2021-10-26 16:56:14 +01:00
git clone https://github.com/louislam/uptime-kuma-wiki.git
cd uptime-kuma-wiki
git remote add production https://github.com/louislam/uptime-kuma.wiki.git
```
#### Push to Production Wiki
2021-12-02 10:15:14 +00:00
```bash
2021-10-26 16:56:14 +01:00
git pull
git push production master
```