Development documentation (MM issue #3252)

.vuepress/config.js

@@ -60,14 +60,23 @@ module.exports = {
         title: "Module Development",
         collapsable: true,
         children: [
-          "development/introduction.md",
-          "development/core-module-file.md",
-          "development/node-helper.md",
-          "development/helper-methods.md",
-          "development/logger.md",
-          "development/notifications.md",
-          "development/weather-provider.md",
-          "development/documentation.md",
+          "module-development/introduction.md",
+          "module-development/core-module-file.md",
+          "module-development/node-helper.md",
+          "module-development/helper-methods.md",
+          "module-development/logger.md",
+          "module-development/notifications.md",
+          "module-development/weather-provider.md",
+          "module-development/documentation.md",
+        ],
+      },
+      {
+        title: "Core Development",
+        collapsable: true,
+        children: [
+          "core-development/introduction.md",
+          "core-development/testing.md",
+          "core-development/debugging.md",
         ],
       },
       {

.vuepress/enhanceApp.js

@@ -0,0 +1,12 @@
+export default ({ router }) => {
+    router.addRoutes([
+        { path: '/development/introduction.html', redirect: '/module-development/introduction.html' },
+        { path: '/development/core-module-file.html', redirect: '/module-development/core-module-file.html' },
+        { path: '/development/node-helper.html', redirect: '/module-development/node-helper.html' },
+        { path: '/development/helper-methods.html', redirect: '/module-development/helper-methods.html' },
+        { path: '/development/logger.html', redirect: '/module-development/logger.html' },
+        { path: '/development/notifications.html', redirect: '/module-development/notifications.html' },
+        { path: '/development/weather-provider.html', redirect: '/module-development/weather-provider.html' },
+        { path: '/development/documentation.html', redirect: '/module-development/documentation.html' }
+    ])
+}

core-development/debugging.md

@@ -0,0 +1,88 @@
+---
+title: Debugging
+---
+
+# Core Development Documentation: Debugging
+
+Tips and tricks for debugging MagicMirror²,
+
+## Make sure dependencies are up-to-date
+
+When you pull a branch, exceptions can be thrown when running MagicMirror²:
+```
+App threw an error during load
+Error: Cannot find module 'ansis'
+Require stack:
+```
+
+If this happens, make sure that dependencies have been updated to latest by executing `npm install`.
+
+## Breakpoints
+
+Node.js has support for [built-in breakpoints](https://nodejs.org/api/debugger.html), or [VSCode](https://code.visualstudio.com/) allows for visual breakpoints and inspecting of objects.
+
+Developer consoles in browsers and the Electron app (typically CTRL+SHIFT+I to toggle open/close) can be used to set client-side breakpoints, step through scripts and inspect variables.
+
+## Logging
+
+While there are no log files produced by the server, info is reported in two different places:
+* The console when running from `npm run start` or `npm run server`.
+    * This is separated into two streams, `console.log()` is output as the `stdout` stream, and
+    * `console.error()` is output as the `stderr` stream.
+    * These can be redirected to files when starting the server. `>` will redirect `stdout`, and `2>` will redirect `stderr`. `2>&1` will combine both streams: `npm run start > out.log 2>&1`
+* The browser's developer console (typically CTRL+SHIFT+I to toggle open/close) will have output from scripts that run on the browser.
+
+The [MMM-Logging](https://github.com/shbatm/MMM-Logging) module can help to gather logs and output to a file, but at a performance cost.
+
+Debug logging is disabled by default, and can be very verbose. It can be enabled in the *config/config.js* file by adding `"DEBUG"` to the `logLevel` key:
+```js
+let config = {
+    // ...
+    logLevel: ["INFO", "LOG", "WARN", "ERROR", "DEBUG"], // Add "DEBUG" for even more logging
+    // ...
+};
+```
+
+If you are using `pm2` to launch MagicMirror², you can use the `logs` command to display lines from each of the `stderr` and `stdout` streams, but not interlaced by time:
+```sh
+pm2 logs --lines=15 # will show 15 lines each from stdout and stderr
+```
+
+There is no capability to identify the module that is producing console output. However, most browsers have the ability to filter logs by a string.
+
+## Date
+
+It can be very useful to set the current date to debug calendar issues. In order to do this, override `Date.now` with a lambda in *config/config.js*:
+
+```js
+Date.now = () => new Date('2023-12-31T14:05:32').valueOf();
+```
+
+This will cause every request for the current time to return the specified time, at least for the core and built-in modules.
+
+Several tests use this to override the current time for the test. See `startApplication()` in *tests/electron/helpers/global-setup.js* as it has a `systemDate` argument to override the system date for tests.
+
+**NOTE:** Some modules may use `new Date()` to get the current date/time, though this is not recommended. If this is the case,
+the external module will not work correctly for date debugging.
+
+## Timezone
+
+The `TZ` environment variable can be used to specify a valid [canonical timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+from the [tz database](https://en.wikipedia.org/wiki/Tz_database).
+
+Several tests do this, such as this example in *tests/electron/helpers/global-setup.js*:
+
+```js
+process.env.TZ = "GMT";
+```
+
+The *package.json* could also be modified to force a timezone for a given script, such as `start:dev`:
+
+```json
+"start:dev": "TZ=Europe/Madrid ./node_modules/.bin/electron js/electron.js dev"
+```
+
+Or when running from the command line (Linux example):
+```sh
+TZ=Europe/Madrid npm run start:dev
+```

core-development/introduction.md

@@ -0,0 +1,39 @@
+---
+title: Introduction
+---
+
+# Core Development Documentation
+
+This documentation describes core MagicMirror² development.
+
+## General
+
+MagicMirror² is a community-driven development effort, and [contributions](../about/contributing.md) are
+welcome!
+
+In general, new features and bug fixes should be tracked against an [issue in the MagicMirror repo](https://github.com/MagicMirrorOrg/MagicMirror/issues).
+It is always a good idea to search existing issues to see if a problem you're experiencing has already been reported,
+or if someone has already suggested a feature you'd like to propose. Creating or finding an issue also starts the
+discussion and helps build consensus around your proposed fix or feature.
+
+The MagicMirror² core is [developed on GitHub](https://github.com/MagicMirrorOrg/MagicMirror/) out of the
+*develop* branch. To begin developing MagicMirror² core, please fork the GitHub project and
+create a new branch based off of the *develop* branch.
+
+When your development is ready for review and testing, create a new *Pull Request* targeting the *develop* branch.
+The development team and other contributors will be able to review your changes and provide feedback, and
+the test system will run automated tests against your changes. Make sure to mention the issue(s) that your Pull
+Request solves.
+
+## Development Environment
+
+Although Node.js applications are typically platform-independent, many of the scripts created for MagicMirror² are
+Linux-based. While Windows/Mac development is possible, you may run into issues. (Improvements here are welcome!)
+
+You will need to have [Node.js installed](https://nodejs.org/en/download). When doing Linux development, on newer
+distributions Node.js is available from package managers.
+
+Many Node.js or experienced Javascript developers have an environment that works for them. New developers
+to Node.js / Electron can download [VSCode for free](https://code.visualstudio.com/download) and use many extensions available for debugging and developing Javascript.
+
+Also checkout [Building Node.js Apps with VSCode](https://code.visualstudio.com/docs/nodejs/nodejs-tutorial).

core-development/testing.md

@@ -0,0 +1,30 @@
+---
+title: Testing
+---
+
+# Core Development Documentation: Testing
+
+Unit tests are important to ensure the quality of the project as changes occur.
+
+All tests are located in the [*tests* top-level directory](https://github.com/MagicMirrorOrg/MagicMirror/tree/master/tests).
+
+## Hierarchy of Tests
+
+Below the *tests* directory are other directories that organize the tests:
+
+* *configs* - Configuration files for tests.
+* *e2e* - End-to-end tests that start and run MagicMirror² in various configurations.
+* *electron* - Electron application tests.
+* *mocks* - Mock-up data for tests.
+* *unit* - Unit tests for utilities and smaller portions of MagicMirror².
+* *utils* - Testing utilities.
+
+## Writing a Test
+
+Almost all pull requests must have test coverage of changes. Usually, it is easier to find an existing test and
+extend it to test your new functionality.
+
+For example, if you were writing a test for a fix in the Calendar module, you might locate *tests/e2e/modules/calendar_spec.js*
+and add an additional test there.
+
+If you have questions about how to write a test, you can also ask in the [MagicMirror forums](https://forum.magicmirror.builders/).

development/introduction.md → module-development/introduction.md

@@ -21,6 +21,8 @@ information in your README file.**
 - What external API's it depends upon, including web links to those
 - Whether the API/request require a key and the user limitations of those. (Is
   it free?)
+- **Do not use `new Date()` for the current timestamp, instead prefer `new Date(Date.now())`
+  as it can be more [easily overridden for debugging](..\core-development\debugging.md#Date)**.
 
 Surely this also help you get better recognition and feedback for your work.
 

development/notifications.md → module-development/notifications.md

@@ -8,10 +8,10 @@ The MagicMirror core has the ability to send notifications to modules. Or even
 better: the modules have the possibility to send notifications to other modules.
 
 Additional technical information on the notifications can be found in the
-[modules' documentation](/development/introduction.md#general-advice):
+[modules' documentation](/module-development/introduction.md#general-advice):
 
-- [notificationReceived](/development/core-module-file.md#subclassable-module-methods)
-- [sendNotification](/development/core-module-file.md#module-instance-methods)
+- [notificationReceived](/module-development/core-module-file.md#subclassable-module-methods)
+- [sendNotification](/module-development/core-module-file.md#module-instance-methods)
 
 # System notifications
 

modules/animate.md

@@ -9,9 +9,9 @@ check the [animate.css](https://animate.style/) library to see a preview of the
 ::: warning Where animation can be used?
 
  - [global module configuration](configuration.html#animated) of a module
- - [this.hide()](../development/core-module-file.html#this-hide-speed-callback-options) function in core module file
- - [this.show()](../development/core-module-file.html#this-show-speed-callback-options) function in core module file
- - [this.updateDom()](../development/core-module-file.html#this-updatedom-speed-options) function in core module file
+ - [this.hide()](../module-development/core-module-file.html#this-hide-speed-callback-options) function in core module file
+ - [this.show()](../module-development/core-module-file.html#this-show-speed-callback-options) function in core module file
+ - [this.updateDom()](../module-development/core-module-file.html#this-updatedom-speed-options) function in core module file
 :::
 
 ## animateIn

modules/introduction.md

@@ -17,7 +17,7 @@ The following modules are installed by default.
 For more available modules, check out out the wiki page
 [MagicMirror² 3rd Party Modules](https://github.com/MagicMirrorOrg/MagicMirror/wiki/3rd-party-modules).
 If you want to build your own modules, check out the
-[MagicMirror² Module Development Documentation](/development/introduction.md)
+[MagicMirror² Module Development Documentation](/module-development/introduction.md)
 and don't forget to add it to the
 [wiki](https://github.com/MagicMirrorOrg/MagicMirror/wiki) and the
 [forum](https://forum.magicmirror.builders/category/7/showcase)!

modules/weather.md

@@ -229,4 +229,4 @@ update.
 ## API Provider Development
 
 If you want to add another API provider checkout the
-[Guide](/development/weather-provider.md).
+[Guide](/module-development/weather-provider.md).