Merge pull request #324 from MagicMirrorOrg/develop

Author: KristjanESPERANTO

.vuepress/config.js

@@ -67,14 +67,23 @@ export default {
         text: "Module Development",
         collapsible: 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",
+        ],
+      },
+      {
+        text: "Core Development",
+        collapsible: 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' }
+    ])
+}

README.md

@@ -2,7 +2,7 @@
 title: Introduction
 ---
 
-![MagicMirror²: The open source modular smart mirror platform. ](./.vuepress/public/header.png)
+![MagicMirror²: The open source modular smart mirror platform. ](/header.png)
 
 <p style="text-align: center">
 	<a href="https://choosealicense.com/licenses/mit">

core-development/debugging.md

@@ -0,0 +1,117 @@
+---
+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,48 @@
+---
+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,34 @@
+---
+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/core-module-file.md module-development/core-module-file.mddevelopment/core-module-file.md renamed to module-development/core-module-file.md

@@ -21,6 +21,9 @@ 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.html#Date)**.
 
 Surely this also help you get better recognition and feedback for your work.