From 1f41f6b540fab13c85fd7d69ee5c3b7b123c57fa Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 03:01:47 +0100 Subject: [PATCH 01/13] reduction --- .github/ISSUE_TEMPLATE/ask_for_help.yml | 19 +- .github/ISSUE_TEMPLATE/bug_report.yml | 2 - .github/ISSUE_TEMPLATE/feature_request.yml | 23 -- .github/ISSUE_TEMPLATE/security_issue.yml | 15 +- .github/PULL_REQUEST_TEMPLATE.md | 17 +- CONTRIBUTING.md | 285 ++++----------------- 6 files changed, 71 insertions(+), 290 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/ask_for_help.yml b/.github/ISSUE_TEMPLATE/ask_for_help.yml index 2156c5be0..ea65488c8 100644 --- a/.github/ISSUE_TEMPLATE/ask_for_help.yml +++ b/.github/ISSUE_TEMPLATE/ask_for_help.yml @@ -10,14 +10,13 @@ body: value: | 🚫 **We kindly ask you to refrain from pinging maintainers unless absolutely necessary. Pings are reserved for critical/urgent issues that require immediate attention.** - **Why**: Reserving pings for urgent matters ensures maintainers can prioritize critical tasks effectively - - type: checkboxes id: no-duplicate-question attributes: label: ⚠️ Please verify that your question has not already been reported description: | - To avoid duplicate reports, please search for any existing issues before submitting a new one. You can find the list of existing issues **[HERE](https://github.com/louislam/uptime-kuma/issues?q=is%3Aissue%20sort%3Acreated-desc%20)**. + To avoid duplicate reports, please search for any existing issues before submitting a new one. + You can find the list of existing issues **[HERE](https://github.com/louislam/uptime-kuma/issues?q=is%3Aissue%20sort%3Acreated-desc%20)**. options: - label: | I have searched the [existing issues](https://github.com/louislam/uptime-kuma/issues?q=is%3Aissue%20sort%3Acreated-desc%20) and found no similar reports. @@ -28,7 +27,8 @@ body: attributes: label: 🛡️ Security Policy description: | - Please review and acknowledge the Security Policy before reporting any security-related issues or bugs. You can find the full Security Policy **[HERE](https://github.com/louislam/uptime-kuma/security/policy)**. + Please review and acknowledge the Security Policy before reporting any security-related issues or bugs. + You can find the full Security Policy **[HERE](https://github.com/louislam/uptime-kuma/security/policy)**. options: - label: | I have read and agree to Uptime Kuma's [Security Policy](https://github.com/louislam/uptime-kuma/security/policy). @@ -41,7 +41,8 @@ body: attributes: label: 📝 Describe your problem description: | - Please walk us through it step by step. Include all important details and add screenshots where appropriate + Please walk us through it step by step. + Include all important details and add screenshots where appropriate placeholder: | Describe what are you asking for ... @@ -50,7 +51,8 @@ body: attributes: label: 📝 Error Message(s) or Log description: | - Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. + Please copy and paste any relevant log output. + This will be automatically formatted into code, so no need for backticks. render: bash session validations: required: false @@ -60,9 +62,10 @@ body: attributes: label: 🐻 Uptime-Kuma Version description: | - What version of Uptime-Kuma are you running? Please do not provide Docker tags like `latest` or `1`. + What version of Uptime-Kuma are you running? + Please do not provide Docker tags like `latest` or `1`. placeholder: | - e.g., 1.23.16 or 2.0.0-beta.2 + e.g. 1.23.16 or 2.0.0-beta.2 validations: required: true diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index d0330c70a..1d0bb1429 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -10,8 +10,6 @@ body: value: | 🚫 **We kindly ask you to refrain from pinging maintainers unless absolutely necessary. Pings are reserved for critical/urgent issues that require immediate attention.** - **Why**: Reserving pings for urgent matters ensures maintainers can prioritize critical tasks effectively - - type: textarea id: related-issues validations: diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 61d647a4f..72f5bb3f6 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -25,29 +25,6 @@ body: placeholder: | Example: This relates to issue #1, which also affects the ... system. It should not be merged because ... - - type: dropdown - id: feature-area - attributes: - label: 🏷️ Feature Request Type - description: | - What kind of feature request is this? - multiple: true - options: - - API / automation options - - New notification-provider - - Change to existing notification-provider - - New monitor - - Change to existing monitor - - Dashboard - - Status-page - - Maintenance - - Deployment - - Certificate expiry - - Settings - - Other - validations: - required: true - - type: textarea id: feature-description validations: diff --git a/.github/ISSUE_TEMPLATE/security_issue.yml b/.github/ISSUE_TEMPLATE/security_issue.yml index fa86d9ddb..4beb090bc 100644 --- a/.github/ISSUE_TEMPLATE/security_issue.yml +++ b/.github/ISSUE_TEMPLATE/security_issue.yml @@ -11,9 +11,12 @@ body: value: | ## ❗ IMPORTANT: DO NOT SHARE VULNERABILITY DETAILS HERE - ## Do not report any upstream dependency issues / scan results by any tools. - - It will be closed immediately without explanation, unless you have a PoC to prove that the upstream issue affects Uptime Kuma. + ## Please do not open issues for upstream dependency scan results. + + Automated security tools often report false-positive issues that are not exploitable in the context of Uptime Kuma. + Reviewing these without concrete impact does not scale for us. + + If you can demonstrate that an upstream issue is actually exploitable in Uptime Kuma (e.g. with a PoC or reproducible steps), we’re happy to take a look. ### ⚠️ Report a Security Vulnerability @@ -30,13 +33,15 @@ body: ## **Step 1: Submit a GitHub Security Advisory** - Right-click the link below and select `Open link in new tab` to access the page. This will keep the security issue open, allowing you to easily return and paste the Advisory URL here later. + Right-click the link below and select `Open link in new tab` to access the page. + This will keep the security issue open, allowing you to easily return and paste the Advisory URL here later. ➡️ [Create a New Security Advisory](https://github.com/louislam/uptime-kuma/security/advisories/new) ## **Step 2: Share the Advisory URL** - Once you've created your advisory, please share the URL below. This will notify Louis Lam and enable them to take the appropriate action. + Once you've created your advisory, please share the URL below. + This will notify Louis Lam and enable them to take the appropriate action. - type: textarea id: github-advisory-url diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 407d97b18..416296f6a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,4 +1,4 @@ -_ℹ️ To keep reviews fast and effective, please make sure you’ve [read our pull request guidelines](https://github.com/louislam/uptime-kuma/blob/master/CONTRIBUTING.md#can-i-create-a-pull-request-for-uptime-kuma)_ +ℹ️ To keep reviews fast and effective, please make sure you’ve [read our pull request guidelines](https://github.com/louislam/uptime-kuma/blob/master/CONTRIBUTING.md#can-i-create-a-pull-request-for-uptime-kuma) ## 📝 Summary of changes done and why they are done @@ -17,13 +17,13 @@ _ℹ️ To keep reviews fast and effective, please make sure you’ve [read our Please follow this checklist to avoid unnecessary back and forth (click to expand) - [ ] ⚠️ If there are Breaking change (a fix or feature that alters existing functionality in a way that could cause issues) I have called them out +- [ ] 🧠 I have disclosed any use of LLMs/AI in this contribution and reviewed all generated content. + I understand that I am responsible for and able to explain every line of code I submit. - [ ] 🔍 My code adheres to the style guidelines of this project. -- [ ] 🦿 I have indicated where (if any) I used an LLM for the contributions -- [ ] ✅ I ran ESLint and other code linters for modified files. - [ ] ⚠️ My changes generate no new warnings. - [ ] 🛠️ I have reviewed and tested my code. - [ ] 📝 I have commented my code, especially in hard-to-understand areas (e.g., using JSDoc for methods). -- [ ] 🤖 My code needed automated testing. I have added them (this is an optional task). +- [ ] 🤖 I added or updated automated tests where appropriate. - [ ] 📄 Documentation updates are included (if applicable). - [ ] 🔒 I have considered potential security impacts and mitigated risks. - [ ] 🧰 Dependency updates are listed and explained. @@ -48,12 +48,3 @@ Please upload the image directly here by pasting it or dragging and dropping. | `DOWN` | ![Before](image-link) | ![After](image-link) | | Certificate-expiry | ![Before](image-link) | ![After](image-link) | | Testing | ![Before](image-link) | ![After](image-link) | - - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4cae2ad0..12ea2c345 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,10 +5,11 @@ requests for Uptime Kuma. I never thought the GitHub community would be so nice! Because of this, I also never thought that other people would actually read and edit my code. Parts of the code are not very well-structured or commented, sorry about that. +If you have ideas or suggestions, please feel free to open an issue or submit a pull request. -The project was created with `vite.js` and is written in `vue3`. Our backend -lives in the `server`-directory and mostly communicates via websockets. Both -frontend and backend share the same `package.json`. +The project was created with `vite` and is written in `vue3`. Our backend +lives in the `server`-directory and mostly communicates via websockets. +Both front and backend share the same `package.json`. For production, the frontend is built into the `dist`-directory and the server (`express.js`) exposes the `dist` directory as the root of the endpoint. For @@ -77,23 +78,17 @@ to review the appropriate one for your contribution. -
Translations / Internationalisation (i18n) (click to expand)

- We use weblate to localise this project into many languages. If you are - unhappy with a translation this is the best start. On how to translate using - weblate, please see - [these instructions](https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md). - - There are two cases in which a change cannot be done in weblate and requires a - PR: - - - A text may not be currently localisable. In this case, **adding a new - language key** via `$t("languageKey")` might be necessary - - language keys need to be **added to `en.json`** to be visible in weblate. If - this has not happened, a PR is appreciated. - - **Adding a new language** requires a new file see - [these instructions](https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md) - - Because maintainer time is precious, junior maintainers may merge - uncontroversial PRs in this area. + Please add **all** strings that are translatable to `src/lang/en.json`. If translation keys are omitted, they cannot be translated. **Do not include any other languages in your initial pull request** (even if it is your mother tongue) to avoid merge conflicts between Weblate and `master`. Once your PR is merged into `master`, the strings can be translated by awesome people donating their language skills. + + We use Weblate to localise this project into many languages. If you want to help translate Uptime Kuma into your language, please see [these instructions on how to translate using Weblate](https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md). + + There are some cases where a change cannot be done directly in Weblate and requires a PR: + + - A text may not yet be localisable. In this case, **adding a new language key** via `{{ $t("Translation key") }}` or [``](https://vue-i18n.intlify.dev/guide/advanced/component.html) might be necessary. + - Language keys need to be **added to `en.json`** to appear in Weblate. If this has not been done, a PR is appreciated. + - **Adding a new language** requires creating a new file. See [these instructions](https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md). + + Because maintainer time is precious, junior maintainers may merge uncontroversial PRs in this area.

@@ -154,6 +149,7 @@ to review the appropriate one for your contribution. - `UP`/`DOWN` - Certificate Expiry via + - Domain Expiry via and a larger time set - Testing (the test button on the notification provider setup page)
@@ -162,10 +158,11 @@ to review the appropriate one for your contribution. ```md | Event | Before | After | - | ------------------ | --------------------- | -------------------- | + |--------------------|-----------------------|----------------------| | `UP` | ![Before](image-link) | ![After](image-link) | | `DOWN` | ![Before](image-link) | ![After](image-link) | | Certificate-expiry | ![Before](image-link) | ![After](image-link) | + | Domain-expiry | ![Before](image-link) | ![After](image-link) | | Testing | ![Before](image-link) | ![After](image-link) | ``` @@ -182,11 +179,9 @@ to review the appropriate one for your contribution. - `server/monitor-types/MONITORING_TYPE.js` is the core of each monitor. the `async check(...)`-function should: - - - throw an error for each fault that is detected with an actionable error - - message - in the happy-path, you should set `heartbeat.msg` to a successful - message and set `heartbeat.status = UP` + - in the happy-path: set `heartbeat.msg` to a successful message and set `heartbeat.status = UP` + - in the unhappy-path: throw an `Error` for each fault that is detected with an actionable error message. + `heartbeat.status = DOWN` should NOT be set, unless you want to ignore retries. - `server/uptime-kuma-server.js` is where the monitoring backend needs to be registered. _If you have an idea how we can skip this step, we would love to @@ -197,7 +192,7 @@ to review the appropriate one for your contribution. credentials - included all the necessary helptexts/placeholder/.. to make sure the notification provider is simple to setup for new users. - include all translations (`{{ $t("Translation key") }}`, - [`i18n-t keypath="Translation key">`](https://vue-i18n.intlify.dev/guide/advanced/component.html)) + [``](https://vue-i18n.intlify.dev/guide/advanced/component.html)) in `src/lang/en.json` to enable our translators to translate this Because maintainer time is precious, junior maintainers may merge @@ -210,8 +205,8 @@ to review the appropriate one for your contribution.

be sure to **create an empty draft pull request or open an issue, so we can - have a discussion first**. This is especially important for a large pull - request or when you don't know if it will be merged or not. + have a discussion first**. + This is especially important for large pull requests or when you don't know if it will be merged or not. Because of the large impact of this work, only senior maintainers may merge PRs in this area. @@ -245,43 +240,9 @@ to review the appropriate one for your contribution. 7. **Select the correct source and target branches**. 8. **Link to related issues** for context. - 9. **Provide a clear and concise description** explaining the changes and - their purpose. - - - **Type of changes** - - - Bugfix (a non-breaking change that resolves an issue) - - New feature (a non-breaking change that adds new functionality) - - Breaking change (a fix or feature that alters existing functionality in a - way that could cause issues) - - User Interface (UI) updates - - New Documentation (addition of new documentation) - - Documentation Update (modification of existing documentation) - - Documentation Update Required (the change requires updates to related - documentation) - - Other (please specify): - - Provide additional details here. - - - **Checklist** - - - My code adheres to the style guidelines of this project. - - I ran ESLint and other code linters for modified files. - - I have reviewed and tested my code. - - I have commented my code, especially in hard-to-understand areas (e.g., - using JSDoc for methods). - - My changes generate no new warnings. - - My code needed automated testing. I have added them (this is an optional - task). - - Documentation updates are included (if applicable). - - I have considered potential security impacts and mitigated risks. - - Dependency updates are listed and explained. - - I have read and understood the - [Pull Request guidelines](#recommended-pull-request-guideline). - - 10. **When publishing your PR, set it as a** `Draft pull request` **to allow - for review and prevent automatic merging.** - 11. **Maintainers will assign relevant labels** (e.g., `A:maintenance`, - `A:notifications`). + 9. **Provide a clear and concise description** of the changes you've made. + 10. **When publishing your PR, set it as a** `Draft pull request` to allow you to self-review and address any issues before a public review. + 11. **Maintainers will assign relevant labels** (e.g., `pr:needs-review`, `pr:needs-testing`, `pr:please address review comments`). 12. **Complete the PR checklist**, ensuring that: - Documentation is updated if necessary. @@ -297,18 +258,12 @@ to review the appropriate one for your contribution. change the status to **Ready for Review** when: - You have implemented all planned changes. - - You have addressed all feedback. - - Your code is fully tested and ready for integration. + - Your code is fully tested and ready for review. - You have updated or created the necessary tests. - You have verified that CI/CD checks pass successfully. -
- - A **work-in-progress (WIP) PR** must stay in **draft status** until everything - is finalized. - - Since maintainer time is valuable, junior maintainers may merge - uncontroversial PRs. + A volunteer maintainer will review your PR as soon as possible. + You can also help by reviewing other PRs or taking a look at open issues.

@@ -335,18 +290,14 @@ to review the appropriate one for your contribution. - Don't modify or delete existing logic without a valid reason. - Don't convert existing code into other programming languages for no reason. -I ([@louislam](https://github.com/louislam)) have the final say. If your pull -request does not meet my expectations, I will reject it, no matter how much time -you spent on it. Therefore, it is essential to have a discussion beforehand. +I ([@louislam](https://github.com/louislam)) have the final say. +If your pull request does not meet my expectations, I will reject it, no matter how much time +you spent on it. -I will assign your pull request to a [milestone], if I plan to review and merge -it. +We will assign your pull request to a [milestone](https://github.com/louislam/uptime-kuma/milestones), if we plan to review and merge it. -[milestone]: https://github.com/louislam/uptime-kuma/milestones - -Please don't rush or ask for an ETA. We have to understand the pull request, -make sure it has no breaking changes and stick to the vision of this project, -especially for large pull requests. +Please don't rush or ask for an ETA. +We have to understand the pull request, make sure it has no breaking changes and stick to the vision of this project, especially for large pull requests. ## I'd Like to Work on an Issue. How Do I Do That? @@ -354,92 +305,9 @@ We have found that assigning people to issues is unnecessary management overhead. Instead, a short comment stating that you want to work on an issue is appreciated, as it saves time for other developers. If you encounter any problems during development, feel free to leave a comment describing what you -are stuck on. +are stuck on, we are here to help. -### Recommended Pull Request Guideline - -Before jumping into coding, it's recommended to initiate a discussion by -creating an empty pull request. This approach allows us to align on the -direction and scope of the feature, ensuring it doesn't conflict with existing -or planned work. It also provides an opportunity to identify potential pitfalls -early on, helping to avoid issues down the line. - -1. **Fork** the [Uptime-Kuma repository]. -2. **Clone** your forked repository to your local machine. -3. **Create a new branch** for your changes (e.g., - `feature/add-new-notification-provider-signal`). -4. **Initiate a discussion before making major changes** by creating an empty - commit: - - ```sh - git commit -m "" --allow-empty - ``` - -5. **Push** your branch to your forked repository. -6. **Open a pull request** using this link: [Compare & Pull Request]. -7. **Select the correct source and target branches**. -8. **Link to related issues** for context. -9. **Provide a clear and concise description** explaining the changes and their - purpose. - - - **Type of changes** - - - Bugfix (a non-breaking change that resolves an issue) - - New feature (a non-breaking change that adds new functionality) - - Breaking change (a fix or feature that alters existing functionality in a - way that could cause issues) - - User Interface (UI) updates - - New Documentation (addition of new documentation) - - Documentation Update (modification of existing documentation) - - Documentation Update Required (the change requires updates to related - documentation) - - Other (please specify): - - Provide additional details here. - - - **Checklist** - - - My code adheres to the style guidelines of this project. - - I ran ESLint and other code linters for modified files. - - I have reviewed and tested my code. - - I have commented my code, especially in hard-to-understand areas (e.g., - using JSDoc for methods). - - My changes generate no new warnings. - - My code needed automated testing. I have added them (this is an optional - task). - - Documentation updates are included (if applicable). - - I have considered potential security impacts and mitigated risks. - - Dependency updates are listed and explained. - - I have read and understood the - [Pull Request guidelines](#recommended-pull-request-guideline). - -10. **When publishing your PR, set it as a** `Draft pull request` **to allow for - review and prevent automatic merging.** -11. **Maintainers will assign relevant labels** (e.g., `A:maintenance`, - `A:notifications`). -12. **Complete the PR checklist**, ensuring that: - - - Documentation is updated if necessary. - - Tests are written or updated. - - CI/CD checks pass successfully. - -13. **Request feedback** from team members to refine your changes before the - final review. - -### When Can You Change the PR Status to "Ready for Review"? - -A PR should remain in **draft status** until all tasks are completed. Only -change the status to **Ready for Review** when: - -- You have implemented all planned changes. -- You have addressed all feedback. -- Your code is fully tested and ready for integration. -- You have updated or created the necessary tests. -- You have verified that CI/CD checks pass successfully. - -A **work-in-progress (WIP) PR** must stay in **draft status** until everything -is finalized. - -## Project Styles +## Project Style I personally do not like something that requires a lot of configuration before you can finally start the app. The goal is to make the Uptime Kuma installation @@ -501,8 +369,6 @@ npm ci ## Dev Server -(2022-04-26 Update) - We can start the frontend dev server and the backend dev server in one command. Port `3000` and port `3001` will be used. @@ -549,16 +415,10 @@ in the `socket.io` handlers. `express.js` is also used to serve: It binds to `0.0.0.0:3000` by default. The frontend dev server is used for development only. -For production, it is not used. It will be compiled to `dist` directory instead. +For production, it is not used. It will be compiled to `dist` directory instead via `npm run build`. You can use Vue.js devtools Chrome extension for debugging. -### Build the frontend - -```bash -npm run build -``` - ### Frontend Details Uptime Kuma Frontend is a single page application (SPA). Most paths are handled @@ -566,7 +426,7 @@ by Vue Router. The router is in `src/router.js` -As you can see, most data in the frontend is stored at the root level, even +Most data in the frontend is stored at the root level, even though you changed the current router to any other pages. The data and socket logic are in `src/mixins/socket.js`. @@ -577,6 +437,8 @@ See: ## Unit Test +To run unit tests, use the following command: + ```bash npm run build npm test @@ -584,8 +446,8 @@ npm test ## Dependencies -Both frontend and backend share the same `package.json`. However, the frontend -dependencies are eventually not used in the production environment, because it +Both frontend and backend share the same `package.json`. +However, the frontend dependencies are eventually not used in the production environment, because it is usually also baked into `dist` files. So: - Frontend dependencies = "devDependencies" @@ -605,26 +467,10 @@ Patch release = the third digit ([Semantic Versioning](https://semver.org/)) If for security / bug / other reasons, a library must be updated, breaking changes need to be checked by the person proposing the change. -## Translations - -Please add **all** the strings which are translatable to `src/lang/en.json` (if -translation keys are omitted, they can not be translated.) - -**Don't include any other languages in your initial pull request** (even if this -is your mother tongue), to avoid merge-conflicts between weblate and `master`. -The translations can then (after merging a PR into `master`) be translated by -awesome people donating their language skills. - -If you want to help by translating Uptime Kuma into your language, please visit -the [instructions on how to translate using weblate]. - -[instructions on how to translate using weblate]: - https://github.com/louislam/uptime-kuma/blob/master/src/lang/README.md - ## Spelling & Grammar -Feel free to correct the grammar in the documentation or code. My mother -language is not English and my grammar is not that great. +Feel free to correct the spelling and grammar in the documentation or code. +None of our mother languages are English. ## Wiki @@ -633,47 +479,8 @@ repo to do that. -## Docker - -### Arch - -- amd64 -- arm64 -- armv7 - -### Docker Tags - -#### v2 - -- `2`, `latest-2`: v2 with full features such as Chromium and bundled MariaDB -- `2.x.x` -- `2-slim`: v2 with basic features -- `2.x.x-slim` -- `beta2`: Latest beta build -- `2.x.x-beta.x` -- `nightly2`: Dev build -- `base2`: Basic Debian setup without Uptime Kuma source code (Full features) -- `base2-slim`: Basic Debian setup without Uptime Kuma source code -- `pr-test2`: For testing pull request without setting up a local environment - -#### v1 - -- `1`, `latest`, `1-debian`, `debian`: Latest version of v1 -- `1.x.x`, `1.x.x-debian` -- `1.x.x-beta.x`: Beta build -- `beta`: Latest beta build -- `nightly`: Dev build -- `base-debian`: Basic Debian setup without Uptime Kuma source code -- `pr-test`: For testing pull request without setting up a local environment -- `base-alpine`: (Deprecated) Basic Alpine setup without Uptime Kuma source code -- `1-alpine`, `alpine`: (Deprecated) -- `1.x.x-alpine`: (Deprecated) - ## Maintainer -Check the latest issues and pull requests: - - ### What is a maintainer and what are their roles? This project has multiple maintainers who specialise in different areas. From 74910e8408c84a8ce88598349ad2c137f3061c6a Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 03:32:49 +0100 Subject: [PATCH 02/13] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12ea2c345..cb24417da 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -426,8 +426,7 @@ by Vue Router. The router is in `src/router.js` -Most data in the frontend is stored at the root level, even -though you changed the current router to any other pages. +Most data in the frontend is stored at the root level, even though the router can navigate to different pages. The data and socket logic are in `src/mixins/socket.js`. From 1e1db1816ed2c3a07d50e7d66b92d33da614f44a Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 03:32:58 +0100 Subject: [PATCH 03/13] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb24417da..51da864cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -469,7 +469,7 @@ changes need to be checked by the person proposing the change. ## Spelling & Grammar Feel free to correct the spelling and grammar in the documentation or code. -None of our mother languages are English. +English is not the native language of any maintainer. ## Wiki From 40b1422352ceb0827e1967fa766215b87518281b Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 03:33:08 +0100 Subject: [PATCH 04/13] Update .github/ISSUE_TEMPLATE/ask_for_help.yml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/ask_for_help.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/ask_for_help.yml b/.github/ISSUE_TEMPLATE/ask_for_help.yml index ea65488c8..d256f5556 100644 --- a/.github/ISSUE_TEMPLATE/ask_for_help.yml +++ b/.github/ISSUE_TEMPLATE/ask_for_help.yml @@ -65,7 +65,7 @@ body: What version of Uptime-Kuma are you running? Please do not provide Docker tags like `latest` or `1`. placeholder: | - e.g. 1.23.16 or 2.0.0-beta.2 + e.g., 1.23.16 or 2.0.0-beta.2 validations: required: true From 3660a691092325f345e4bb61fd35490f320628b6 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 03:33:23 +0100 Subject: [PATCH 05/13] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 51da864cf..ac15416a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,6 @@ requests for Uptime Kuma. I never thought the GitHub community would be so nice! Because of this, I also never thought that other people would actually read and edit my code. Parts of the code are not very well-structured or commented, sorry about that. -If you have ideas or suggestions, please feel free to open an issue or submit a pull request. The project was created with `vite` and is written in `vue3`. Our backend lives in the `server`-directory and mostly communicates via websockets. From 47e2968b26d57f90ac4ca66278d8520172f76e4e Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 03:33:30 +0100 Subject: [PATCH 06/13] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac15416a3..a04d6b851 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ about that. The project was created with `vite` and is written in `vue3`. Our backend lives in the `server`-directory and mostly communicates via websockets. -Both front and backend share the same `package.json`. +Both frontend and backend share the same `package.json`. For production, the frontend is built into the `dist`-directory and the server (`express.js`) exposes the `dist` directory as the root of the endpoint. For From f1cd427d0036c9bf2a624c2561186cecd15a91b3 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 03:49:30 +0100 Subject: [PATCH 07/13] improve the "As a first time contributor" guidance --- CONTRIBUTING.md | 58 ++++++++++++++++++++----------------------------- 1 file changed, 23 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a04d6b851..4b01f8e39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -176,11 +176,11 @@ to review the appropriate one for your contribution. To set up a new notification provider these files need to be modified/created: - - `server/monitor-types/MONITORING_TYPE.js` is the core of each monitor. the - `async check(...)`-function should: + - `server/monitor-types/MONITORING_TYPE.js` is the core of each monitor. + The `async check(...)`-function should: - in the happy-path: set `heartbeat.msg` to a successful message and set `heartbeat.status = UP` - in the unhappy-path: throw an `Error` for each fault that is detected with an actionable error message. - `heartbeat.status = DOWN` should NOT be set, unless you want to ignore retries. + - NEVER set `heartbeat.status = DOWN` unless you want to explicitly ignore retries. - `server/uptime-kuma-server.js` is where the monitoring backend needs to be registered. _If you have an idea how we can skip this step, we would love to @@ -213,48 +213,39 @@ to review the appropriate one for your contribution.

--
Pull Request Guidelines (click to expand) +-
As a first time contributor (click to expand)

- ## Steps to Submit a Pull Request - - 1. **Fork** the [Uptime-Kuma repository]. - - [Uptime-Kuma repository]: https://github.com/louislam/uptime-kuma/ + Contributing is easy and fun. We will guide you through the process: + 1. **Fork** the [Uptime-Kuma repository](https://github.com/louislam/uptime-kuma/) 2. **Clone** your forked repository to your local machine. - 3. **Create a new branch** for your changes (e.g., - `feature/add-new-notification-provider-signal`). - 4. **Initiate a discussion before making major changes** by creating an empty - commit: + 3. **Create a new branch** for your changes (e.g., `signal-notification-provider`) + 4. (large changes or big features only) + + Please discuss all major changes or big features with maintainers before making them. + This will save us all time and effort. + You can do this by: ```sh git commit -m "" --allow-empty + git push origin ``` - - 5. **Push** your branch to your forked repository. - 6. **Open a pull request** using this link: [Compare & Pull Request]. - - [Compare & Pull Request]: https://github.com/louislam/uptime-kuma/compare/ - - 7. **Select the correct source and target branches**. - 8. **Link to related issues** for context. - 9. **Provide a clear and concise description** of the changes you've made. - 10. **When publishing your PR, set it as a** `Draft pull request` to allow you to self-review and address any issues before a public review. - 11. **Maintainers will assign relevant labels** (e.g., `pr:needs-review`, `pr:needs-testing`, `pr:please address review comments`). - 12. **Complete the PR checklist**, ensuring that: - + 5. **Open a pull request** using this link: [Compare & Pull Request](https://github.com/louislam/uptime-kuma/compare/) + 6. **Select the correct source and target branches**. + 7. **Link to related issues** for context. + 8. **Provide a clear and concise description** of the changes you've made. + 9. **When publishing your PR, set it as a** `Draft pull request` to allow you to self-review and address any issues before a public review. + 10. **Complete the PR checklist**, ensuring that: - Documentation is updated if necessary. - Tests are written or updated. - CI/CD checks pass successfully. - - 13. **Request feedback** from team members to refine your changes before the - final review. + 11. **Request feedback** from team/community members to refine your changes before the final review. ## When Can You Change the PR Status to "Ready for Review"? - A PR should remain in **draft status** until all tasks are completed. Only - change the status to **Ready for Review** when: + A PR should remain in **draft status** until all tasks are completed. + Only change the status to **Ready for Review** when: - You have implemented all planned changes. - Your code is fully tested and ready for review. @@ -262,10 +253,7 @@ to review the appropriate one for your contribution. - You have verified that CI/CD checks pass successfully. A volunteer maintainer will review your PR as soon as possible. - You can also help by reviewing other PRs or taking a look at open issues. - -

-
+ You can help us by reviewing other PRs or taking a look at open issues. ## The following rules are essential for making your PR mergable From f56dce188e51a5a65547c5de988669d14e463d28 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 03:55:52 +0100 Subject: [PATCH 08/13] improve the contributing guide --- CONTRIBUTING.md | 43 +++++++++++++++++++------------------------ 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b01f8e39..cafa31207 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,8 @@ Because of this, I also never thought that other people would actually read and edit my code. Parts of the code are not very well-structured or commented, sorry about that. +Before you start, please read our [Code of Conduct](CODE_OF_CONDUCT.md) to understand our community standards. + The project was created with `vite` and is written in `vue3`. Our backend lives in the `server`-directory and mostly communicates via websockets. Both frontend and backend share the same `package.json`. @@ -206,6 +208,7 @@ to review the appropriate one for your contribution. be sure to **create an empty draft pull request or open an issue, so we can have a discussion first**. This is especially important for large pull requests or when you don't know if it will be merged or not. + When adding new features, please also add tests to ensure your changes work as expected and to prevent future regressions. Because of the large impact of this work, only senior maintainers may merge PRs in this area. @@ -218,29 +221,15 @@ to review the appropriate one for your contribution. Contributing is easy and fun. We will guide you through the process: - 1. **Fork** the [Uptime-Kuma repository](https://github.com/louislam/uptime-kuma/) - 2. **Clone** your forked repository to your local machine. - 3. **Create a new branch** for your changes (e.g., `signal-notification-provider`) - 4. (large changes or big features only) - - Please discuss all major changes or big features with maintainers before making them. - This will save us all time and effort. - You can do this by: - - ```sh - git commit -m "" --allow-empty - git push origin - ``` - 5. **Open a pull request** using this link: [Compare & Pull Request](https://github.com/louislam/uptime-kuma/compare/) - 6. **Select the correct source and target branches**. - 7. **Link to related issues** for context. - 8. **Provide a clear and concise description** of the changes you've made. - 9. **When publishing your PR, set it as a** `Draft pull request` to allow you to self-review and address any issues before a public review. - 10. **Complete the PR checklist**, ensuring that: - - Documentation is updated if necessary. - - Tests are written or updated. - - CI/CD checks pass successfully. - 11. **Request feedback** from team/community members to refine your changes before the final review. + 1. **Fork** the [Uptime-Kuma repository](https://github.com/louislam/uptime-kuma/) and **clone** it to your local machine. + 2. **Create a new branch** for your changes (e.g., `signal-notification-provider`). + 3. **Make your changes** and **commit** them with a clear message. + 4. **Push** your changes to your forked repository. + 5. **Open a pull request** to the `master` branch of the Uptime Kuma repository. + - For large changes, please open a **draft pull request** first to discuss the changes with the maintainers. + 6. **Provide a clear and concise description** of the changes you've made and link any related issues. + 7. **Complete the PR checklist** and make sure all CI checks pass. + 8. **Request a review** when your pull request is ready. ## When Can You Change the PR Status to "Ready for Review"? @@ -277,6 +266,12 @@ to review the appropriate one for your contribution. - Don't modify or delete existing logic without a valid reason. - Don't convert existing code into other programming languages for no reason. +### Continuous Integration + +All pull requests must pass our continuous integration checks. These checks include: +- **Linting**: We use ESLint and Stylelint to enforce code style. You can run the linter locally with `npm run lint`. +- **Testing**: We use Playwright for end-to-end tests and have a suite of backend tests. You can run the tests locally with `npm test`. + I ([@louislam](https://github.com/louislam)) have the final say. If your pull request does not meet my expectations, I will reject it, no matter how much time you spent on it. @@ -331,7 +326,7 @@ as easy as installing a mobile app. ## Tools -- [`Node.js`](https://nodejs.org/) >= 18 +- [`Node.js`](https://nodejs.org/) >= 20.4.0 - [`npm`](https://www.npmjs.com/) >= 9.3 - [`git`](https://git-scm.com/) - IDE that supports [`ESLint`](https://eslint.org/) and EditorConfig (I am using From 7cc9aa0d9ffeaa6dcc62597da2ab36d56c413c49 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 04:10:59 +0100 Subject: [PATCH 09/13] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cafa31207..5eb0a0873 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -244,7 +244,7 @@ to review the appropriate one for your contribution. A volunteer maintainer will review your PR as soon as possible. You can help us by reviewing other PRs or taking a look at open issues. -## The following rules are essential for making your PR mergable +## The following rules are essential for making your PR mergeable - Merging multiple issues by a huge PR is more difficult to review and causes conflicts with other PRs. Please From fccb2ee0f11823869b9f20240375c1df97a4726b Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 04:11:10 +0100 Subject: [PATCH 10/13] Update .github/ISSUE_TEMPLATE/ask_for_help.yml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/ask_for_help.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/ask_for_help.yml b/.github/ISSUE_TEMPLATE/ask_for_help.yml index d256f5556..312c09445 100644 --- a/.github/ISSUE_TEMPLATE/ask_for_help.yml +++ b/.github/ISSUE_TEMPLATE/ask_for_help.yml @@ -42,7 +42,7 @@ body: label: 📝 Describe your problem description: | Please walk us through it step by step. - Include all important details and add screenshots where appropriate + Include all important details and add screenshots where appropriate. placeholder: | Describe what are you asking for ... From 05cc1a3970e86f54d30b75adb2bcfc9a11cf16b4 Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 04:11:57 +0100 Subject: [PATCH 11/13] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5eb0a0873..338bf2d2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -451,7 +451,7 @@ changes need to be checked by the person proposing the change. ## Spelling & Grammar Feel free to correct the spelling and grammar in the documentation or code. -English is not the native language of any maintainer. +English is not the native language of the maintainers. ## Wiki From 41ae192ad773b0c1cbb1727cb4030856fab8bbcf Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 04:12:17 +0100 Subject: [PATCH 12/13] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 338bf2d2c..ea487e523 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -287,7 +287,7 @@ We have found that assigning people to issues is unnecessary management overhead. Instead, a short comment stating that you want to work on an issue is appreciated, as it saves time for other developers. If you encounter any problems during development, feel free to leave a comment describing what you -are stuck on, we are here to help. +are stuck on. We are here to help. ## Project Style From 0cd086f2d6f9ce3bc06367780d533c4b641dd4cf Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sat, 3 Jan 2026 04:12:28 +0100 Subject: [PATCH 13/13] Update CONTRIBUTING.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea487e523..d212a5af0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,7 +216,7 @@ to review the appropriate one for your contribution.

--
As a first time contributor (click to expand) +-
As a First-Time Contributor (click to expand)

Contributing is easy and fun. We will guide you through the process: