Security Fixes (click to expand)
-
+
Submitting security fixes is something that may put the community at risk.
- Please read through our [security policy](SECURITY.md) and submit vulnerabilities via an [advisory](https://github.com/louislam/uptime-kuma/security/advisories/new) + [issue](https://github.com/louislam/uptime-kuma/issues/new?assignees=&labels=help&template=security.md) instead.
- We encourage you to submit how to fix a vulnerability if you know how to, this is not required.
- Following the security policy allows us to properly test, fix bugs.
- This review allows us to notice, if there are any changes necessary to unrelated parts like the documentation.
+ Please read through our [security policy](SECURITY.md) and submit
+ vulnerabilities via an [advisory] + [issue] instead. We encourage you to
+ submit how to fix a vulnerability if you know how to, this is not required.
+ Following the security policy allows us to properly test, fix bugs. This
+ review allows us to notice, if there are any changes necessary to unrelated
+ parts like the documentation.
[**PLEASE SEE OUR SECURITY POLICY.**](SECURITY.md)
-
+
+ [advisory]: https://github.com/louislam/uptime-kuma/security/advisories/new
+ [issue]:
+ https://github.com/louislam/uptime-kuma/issues/new?template=security_issue.yml
+
small, non-breaking bug fixes
+
+- Small, Non-Breaking Bug Fixes (click to expand)
-
+
If you come across a bug and think you can solve, we appreciate your work.
Please make sure that you follow these rules:
- - keep the PR as small as possible, fix only one thing at a time => keeping it reviewable
- - test that your code does what you claim it does.
-
- Because maintainer time is precious, junior maintainers may merge uncontroversial PRs in this area.
-
- translations / internationalisation (i18n)
-
-
- 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 nessesary
- - 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.
-
- new notification providers
-
-
- To set up a new notification provider these files need to be modified/created:
- - `server/notification-providers/PROVIDER_NAME.js` is where the heart of the notification provider lives.
- - Both `monitorJSON` and `heartbeatJSON` can be `null` for some events.
- If both are `null`, this is a general testing message, but if just `heartbeatJSON` is `null` this is a certificate expiry.
- - Please wrap the axios call into a
- ```js
- try {
- let result = await axios.post(...);
- if (result.status === ...) ...
- } catch (error) {
- this.throwGeneralAxiosError(error);
- }
- ```
- - `server/notification.js` is where the backend of the notification provider needs to be registered.
- *If you have an idea how we can skip this step, we would love to hear about it ^^*
- - `src/components/NotificationDialog.vue` you need to decide if the provider is a regional or a global one and add it with a name to the respective list
- - `src/components/notifications/PROVIDER_NAME.vue` is where the frontend of each provider lives.
- Please make sure that you have:
- - used `HiddenInput` for secret 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)) in `src/lang/en.json` to enable our translators to translate this
- - `src/components/notifications/index.js` is where the frontend of the provider needs to be registered.
- *If you have an idea how we can skip this step, we would love to hear about it ^^*
- Offering notifications is close to the core of what we are as an uptime monitor.
- Therefore, making sure that they work is also really important.
- Because testing notification providers is quite time intensive, we mostly offload this onto the person contributing a notification provider.
-
- To make sure you have tested the notification provider, please include screenshots of the following events in the pull-request description:
- - `UP`/`DOWN`
- - Certificate Expiry via https://expired.badssl.com/
- - Testing (the test button on the notification provider setup page)
-
- Using the following way to format this is encouraged:
- ```md
- | Event | Before | After |
- ------------------
- | `UP` | paste-image-here | paste-image-here |
- | `DOWN` | paste-image-here | paste-image-here |
- | Certificate-expiry | paste-image-here | paste-image-here |
- | Testing | paste-image-here | paste-image-here |
+ - keep the PR as small as possible, fix only one thing at a time => keeping it
+ reviewable
+ - test that your code does what you claim it does.
+
+ Because maintainer time is precious, junior maintainers may merge
+ uncontroversial PRs in this area.
+
+
+ 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 nessesary
+ - 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.
+
+
+ New Notification Providers (click to expand)
+
+
+ To set up a new notification provider these files need to be modified/created:
+
+ - `server/notification-providers/PROVIDER_NAME.js` is where the heart of the
+ notification provider lives.
+
+ - Both `monitorJSON` and `heartbeatJSON` can be `null` for some events. If
+
+ both are `null`, this is a general testing message, but if just
+ `heartbeatJSON` is `null` this is a certificate expiry.
+
+ - Please wrap the axios call into a
+
+ ```js
+ try {
+ let result = await axios.post(...);
+ if (result.status === ...) ...
+ } catch (error) {
+ this.throwGeneralAxiosError(error);
+ }
```
- Because maintainer time is precious, junior maintainers may merge uncontroversial PRs in this area.
+ - `server/notification.js` is where the backend of the notification provider
+ needs to be registered. _If you have an idea how we can skip this step, we
+ would love to hear about it ^^_
+
+ - `src/components/NotificationDialog.vue` you need to decide if the provider
+ is a regional or a global one and add it with a name to the respective list
+
+ - `src/components/notifications/PROVIDER_NAME.vue` is where the frontend of
+ each provider lives. Please make sure that you have:
+
+ - used `HiddenInput` for secret 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))
+ in `src/lang/en.json` to enable our translators to translate this
+
+ - `src/components/notifications/index.js` is where the frontend of the
+ provider needs to be registered. _If you have an idea how we can skip this
+ step, we would love to hear about it ^^_
+
+ Offering notifications is close to the core of what we are as an uptime
+ monitor. Therefore, making sure that they work is also really important.
+ Because testing notification providers is quite time intensive, we mostly
+ offload this onto the person contributing a notification provider.
+
+ To make sure you have tested the notification provider, please include
+ screenshots of the following events in the pull-request description:
+
+ - `UP`/`DOWN`
+ - Certificate Expiry via
+ - Testing (the test button on the notification provider setup page)
+
+
+
+ Using the following way to format this is encouraged:
+
+ ```md
+ | Event | Before | After |
+ | ------------------ | --------------------- | -------------------- |
+ | `UP` |  |  |
+ | `DOWN` |  |  |
+ | Certificate-expiry |  |  |
+ | Testing |  |  |
+ ```
+
+ Because maintainer time is precious, junior maintainers may merge
+ uncontroversial PRs in this area.
+
new monitoring types
+
+- New Monitoring Types (click to expand)
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:
- - 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`
- - `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 hear about it ^^*
+
+ - `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`
+
+ - `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
+ hear about it ^^_
+
- `src/pages/EditMonitor.vue` is the shared frontend users interact with.
- Please make sure that you have:
- - used `HiddenInput` for secret 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)) in `src/lang/en.json` to enable our translators to translate this
- -
+ Please make sure that you have: - used `HiddenInput` for secret
+ 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))
+ in `src/lang/en.json` to enable our translators to translate this
+ Because maintainer time is precious, junior maintainers may merge
+ uncontroversial PRs in this area.
- Because maintainer time is precious, junior maintainers may merge uncontroversial PRs in this area.
-
- new features/ major changes / breaking bugfixes
-
-
- 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.
-
- Because of the large impact of this work, only senior maintainers may merge PRs in this area.
New Features / Major Changes / Breaking Bugfixes (click to expand)
+
+
+ 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.
+
+ Because of the large impact of this work, only senior maintainers may
+ merge PRs in this area.
+
+
+ Pull Request Guidelines (click to expand)
+
+
+ ## Steps to Submit a Pull Request
+
+ 1. **Fork** the [Uptime-Kuma repository].
+
+ [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:
+
+ ```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].
+
+ [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** 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.
+
+ Since maintainer time is valuable, junior maintainers may merge
+ uncontroversial PRs.
+
+
+ Set up a Docker Builder
+
+- Set up a Docker Builder (click to expand)
- amd64, armv7 using local.
- - arm64 using remote arm64 cpu, as the emulator is too slow and can no longer pass the `npm ci` command.
- 1. Add the public key to the remote server.
- 2. Add the remote context. The remote machine must be arm64 and installed Docker CE.
- ```
- docker context create oracle-arm64-jp --docker "host=ssh://root@100.107.174.88"
- ```
- 3. Create a new builder.
- ```
- docker buildx create --name kuma-builder --platform linux/amd64,linux/arm/v7
- docker buildx use kuma-builder
- docker buildx inspect --bootstrap
- ```
- 4. Append the remote context to the builder.
- ```
- docker buildx create --append --name kuma-builder --platform linux/arm64 oracle-arm64-jp
- ```
- 5. Verify the builder and check if the builder is using `kuma-builder`.
- ```
- docker buildx inspect kuma-builder
- docker buildx ls
- ```
+ - arm64 using remote arm64 cpu, as the emulator is too slow and can no longer
+ pass the `npm ci` command.
+
+ 1. Add the public key to the remote server.
+ 2. Add the remote context. The remote machine must be arm64 and installed
+ Docker CE.
+
+ ```bash
+ docker context create oracle-arm64-jp --docker "host=ssh://root@100.107.174.88"
+ ```
+
+ 3. Create a new builder.
+
+ ```bash
+ docker buildx create --name kuma-builder --platform linux/amd64,linux/arm/v7
+ docker buildx use kuma-builder
+ docker buildx inspect --bootstrap
+ ```
+
+ 4. Append the remote context to the builder.
+
+ ```bash
+ docker buildx create --append --name kuma-builder --platform linux/arm64 oracle-arm64-jp
+ ```
+
+ 5. Verify the builder and check if the builder is using `kuma-builder`.
+ `docker buildx inspect kuma-builder docker buildx ls`
+
Release
+
+- Release (click to expand)
1. Draft a release note
2. Make sure the repo is cleared
- 3. If the healthcheck is updated, remember to re-compile it: `npm run build-docker-builder-go`
+ 3. If the healthcheck is updated, remember to re-compile it:
+ `npm run build-docker-builder-go`
4. `npm run release-final` with env vars: `VERSION` and `GITHUB_TOKEN`
5. Wait until the `Press any key to continue`
6. `git push`
@@ -463,13 +740,16 @@ We have a few procedures we follow. These are documented here:
These Items need to be checked:
- - [ ] 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)
+ - [ ] Check all tags is fine on
+
+ - [ ] Try the Docker image with tag 1.X.X (Clean install / amd64 / arm64 /
+ armv7)
- [ ] Try clean installation with Node.js
-
+
Release Beta
+
+- Release Beta (click to expand)
1. Draft a release note, check `This is a pre-release`
@@ -478,35 +758,37 @@ We have a few procedures we follow. These are documented here:
4. Wait until the `Press any key to continue`
5. Publish the release note as `1.X.X-beta.X`
6. Press any key to continue
-
+
Release Wiki
+
+- Release Wiki (click to expand)
**Setup Repo**
-
+
```bash
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**
-
+
```bash
git pull
git push production master
```
-
+
Change the base of a pull request such as master to 1.23.X
+
+- Change the base of a pull request such as master to 1.23.X (click to expand)
-
+
```bash
git rebase --onto
```
-
+