Merge branch 'master' into feature/email-2.2

StorytellerCZ · StorytellerCZ · commit 3de06c2a71db · 2021-09-15T12:53:29.000+02:00
diff --git a/README.md b/README.md
@@ -31,3 +31,37 @@ To generate the api boxes, the site uses a file `data/data.js` which is generate
 #### Starting hexo
 
 Ensure you've run `npm install`. Then simply `npm start`.
+
+### Developing with local meteor source
+
+When developing jsdoc documentation within the meteor code you will
+need to make some local modifications to get the documentation to work locally for testing.
+
+1. Modify `url` in `_config.yml` so links within `localhost:4000` will not jump out to `https://docs.meteor.com`
+```diff
+- url: http://docs.meteor.com/
++ url: http://localhost:4000/
+```
+2. reconnect the meteor submodule in `/code` to your local meteor folder.
+```bash
+# REMOVE submodule
+# Remove the submodule entry from .git/config
+git submodule deinit -f code
+
+# Remove the submodule directory from the superproject's
+# .git/modules directory
+rm -rf .git/modules/code
+
+# Remove the entry in .gitmodules and remove the submodule directory
+# located at path/to/submodule
+git rm -f code
+
+# ADD your local meteor submodule
+git submodule add /path/to/local/meteor code
+```
+
+3. Hexo builds if you are just changing md files in sources then
+hexo will watch for changes and update.  If you are making changes
+in the `/code` folder then you will need to `npm clean && npm start`.
+
+Of course, do not commit any of these changes.
diff --git a/_config.yml b/_config.yml
@@ -1,6 +1,7 @@
 title: Meteor API Docs
 subtitle: API Docs
 versions:
+  - '2.4'
   - '2.3'
   - '2.2'
   - '2.1'
@@ -26,6 +27,7 @@ sidebar_categories:
   null:
     - index
     - changelog
+    - install
   API:
     - api/core
     - api/pubsub
@@ -49,6 +51,7 @@ sidebar_categories:
     - api/assets
     - api/packagejs
     - api/mobile-config
+    - api/environment
   Packages:
     - packages/accounts-ui
     - packages/appcache
diff --git a/jsdoc/docdata-jsdoc-template/publish.js b/jsdoc/docdata-jsdoc-template/publish.js
@@ -48,7 +48,7 @@
     if (entry.meta && entry.meta.path) {
       var packagesFolder = 'packages/';
       var index = entry.meta.path.indexOf(packagesFolder);
-      if (index != -1) {
+      if (index != -1 && !entry.isprototype) {
         var fullFilePath = entry.meta.path.substr(index + packagesFolder.length) + '/' + entry.meta.filename;
         entry.filepath = fullFilePath;
         entry.lineno = entry.meta.lineno;
diff --git a/package-lock.json b/package-lock.json
diff --git a/scripts/api-box.js b/scripts/api-box.js
@@ -156,6 +156,7 @@ var importName = function(doc) {
   const noImportNeeded = !doc.module
     || doc.scope === 'instance'
     || doc.ishelper
+    || doc.isprototype
     || doc.istemplate;
 
   // override the above we've explicitly decided to (i.e. Template.foo.X)
diff --git a/source/api/core.md b/source/api/core.md
@@ -3,6 +3,10 @@ title: Core
 description: Documentation of core Meteor functions.
 ---
 
+If you prefer to watch the video, click below. 
+
+{% youtube 6RRVU0-Vvm8 %}
+
 {% apibox "Meteor.isClient" %}
 {% apibox "Meteor.isServer" %}
 
diff --git a/source/api/environment.md b/source/api/environment.md
@@ -0,0 +1,29 @@
+---
+title: Environment
+description: Documentation of how to use Meteor.EnvironmentVariable
+---
+
+Meteor runs most app code within Fibers, which allows keeping track of the context a function is running in. `Meteor.EnvironmentVariable` works with `Meteor.bindEnvironment`, promises, and many other Meteor API's to preserve the context in async code. Some examples of how it is used in Meteor are to store the current user in methods, and record which arguments have been checked when using `audit-argument-checks`.
+
+```js
+const currentRequest = new Meteor.EnvironmentVariable();
+
+function log(message) {
+  const requestId = currentRequest.get() || 'None';
+  console.log(`[${requestId}]`, message);
+}
+
+
+currentRequest.withValue('12345', () => {
+  log('Handling request'); // Logs: [12345] Handling request
+});
+
+```
+
+{% apibox "Meteor.EnvironmentVariable" %}
+
+{% apibox "Meteor.EnvironmentVariable.get" %}
+
+{% apibox "Meteor.EnvironmentVariable.withValue" %}
+
+{% apibox "Meteor.bindEnvironment" %}
diff --git a/source/api/methods.md b/source/api/methods.md
@@ -5,7 +5,9 @@ description: Documentation of Meteor's Method (Remote Procedure Call) API.
 
 Methods are remote functions that Meteor clients can invoke with [`Meteor.call`](#Meteor-call).
 
-If you prefer video watch [Meteor Methods 101](https://www.youtube.com/watch?v=2uoeBq8SF9E) in our [YouTube Channel](https://www.youtube.com/channel/UC3fBiJrFFMhKlsWM46AsAYw).
+If you prefer to watch the video, click below. 
+
+{% youtube 2uoeBq8SF9E %}
 
 {% apibox "Meteor.methods" %}
 
diff --git a/source/api/pubsub.md b/source/api/pubsub.md
@@ -6,6 +6,10 @@ description: Documentation of Meteor's publication and subscription API.
 These functions control how Meteor servers publish sets of records and
 how clients can subscribe to those sets.
 
+If you prefer to watch the video, click below. 
+
+{% youtube RH2RxKgkPJY %}
+
 {% apibox "Meteor.publish" %}
 
 To publish records to clients, call `Meteor.publish` on the server with
diff --git a/source/commandline.md b/source/commandline.md
@@ -33,8 +33,8 @@ required.
 This is the default command. Simply running `meteor` is the
 same as `meteor run`.
 
-To pass additional options to Node.js use the `SERVER_NODE_OPTIONS` environment variable.
-For example: `SERVER_NODE_OPTIONS='--inspect'` or `SERVER_NODE_OPTIONS='--inspect-brk'`
+To pass additional options to Node.js use the `SERVER_NODE_OPTIONS` environment variable. E.g. for Windows PowerShell: 
+`$env:SERVER_NODE_OPTIONS = '--inspect' | meteor run`. Or for Linux: `SERVER_NODE_OPTIONS=--inspect-brk meteor run`.
 
 To specify a port to listen on (instead of the default 3000), use `--port [PORT]`.
 (The development server also uses port `N+1` for the default MongoDB instance)
diff --git a/source/index.md b/source/index.md
@@ -17,6 +17,8 @@ Meteor is a full-stack JavaScript platform for developing modern web and mobile
 
 <h2 id="learning-more">Meteor resources</h2>
 
+1. First, learn how to install meteor in the [installation section](/install.html).
+
 1. The place to get started with Meteor is the [tutorials page](https://www.meteor.com/developers/tutorials).
 
 1. [Meteor Examples](https://github.com/meteor/examples) is a list of examples using Meteor. You can also include your example with Meteor.
diff --git a/source/install.md b/source/install.md
@@ -0,0 +1,59 @@
+---
+title: Install
+---
+Meteor currently supports **OS X, Windows, and Linux**. Only 64-bit is supported.
+Apple M1 is only supported through Rosetta at this moment.
+
+### Prerequisites and useful information
+
+- Meteor requires Node.js 8 or newer installed for running the npm installer.
+- Meteor supports Windows 7/Windows Server 2008 R2 and up.
+- Disabling antivirus (Windows Defender, etc.) will improve performance.
+- For compatibility, Linux binaries are built with CentOS 6.4 i386/amd64.
+- iOS development requires the latest Xcode.
+- **Do not install meteor npm in your project's package.json by any means, the npm library is only an installer.**
+
+### Installation
+
+Install the latest official Meteor release from your terminal:
+
+```bash
+npm install -g meteor
+```
+
+If your user doesn't have permission to install global binaries, and you need to use sudo, it's necessary to append *--unsafe-perm* to the above command:
+
+```bash
+sudo npm install -g meteor --unsafe-perm
+```
+
+We strongly discourage the usage of Node.js or Meteor with root permissions.
+Only run the above command with sudo if you know what you are doing.
+
+If you only use sudo because of a distribution default permission system, [check this link for fixing it](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
+
+For Apple M1 computers, you can append Rosetta prefix as following:
+
+```bash
+
+arch -x86_64 npm install -g meteor
+
+```
+
+or select Terminal in the Applications folder, press CMD(⌘)+I and check the "Open using Rosetta" option.
+
+We currently don't support Apple M1 native binaries as the latest meteor release uses Node.js 14 which doesn't have support for it until now. More info in our repository, [here](https://github.com/meteor/meteor/issues/11249#issuecomment-734327204).
+
+
+### Legacy Installation Method
+
+For Linux and OS X, we are still providing the legacy installation method which uses a bash script and doesn't depend on Node.
+
+```bash
+curl https://install.meteor.com/ | sh
+```
+
+This installation method is not maintained anymore, and you should always use the NPM one.
+
+
+
diff --git a/source/packages/modules.md b/source/packages/modules.md
@@ -3,19 +3,36 @@ title: modules
 description: Documentation of Meteor's `modules` package.
 ---
 
-Though Meteor 1.2 introduced support for [many new ECMAScript 2015 features](https://github.com/meteor/meteor/blob/devel/packages/ecmascript/README.md#supported-es2015-features), one of the most notable omissions was [ES2015 `import` and `export` syntax](http://exploringjs.com/es6/ch_modules.html). Meteor 1.3 fills that gap with a fully standards-compliant module system that works on both the client and the server, solves multiple long-standing problems for Meteor applications (such as controlling file load order), and yet maintains full backwards compatibility with existing Meteor code. This document explains the usage and key features of the new module system.
+This document explains the usage and key features of the module system used by Meteor.
+
+> Meteor 1.2 introduced support for [many new ECMAScript 2015 features](https://github.com/meteor/meteor/blob/devel/packages/ecmascript/README.md#supported-es2015-features), one of the most notable omissions was [ES2015 `import` and `export` syntax](http://exploringjs.com/es6/ch_modules.html). 
+
+> Meteor 1.3 filled the gap with a fully standards-compliant module system that works on both the client and the server.
+
+> Meteor 1.7 introduced `meteor.mainModule` and `meteor.testModule` to `package.json` so Meteor doesn't need special folders anymore for js resources. Also doesn't need to eager load js resources.
+
+By design, `meteor.mainModule` only affect js resources. For non-js resources, there are still some things that can only be done within imports:
+
+- only stylesheets within imports can be dynamically imported
+- you can only control the load order of stylesheets by importing them in js if the stylesheets are within imports
+
+Any non-js resource outside of imports (and some other special folders) are still eagerly loaded. 
+
+> You can read more about these differences in this [comment](https://github.com/meteor/meteor/pull/11381#issuecomment-818816052).
 
 ## Enabling modules
 
-We think you’re going to love the new module system, and that's why it will be installed by default for all new apps and packages. Nevertheless, the `modules` package is totally optional, and it will be up to you to add it to existing apps and/or packages.
+It is installed by default for all new apps and packages. Nevertheless, the `modules` package is totally optional.
+
+If you want to add it to existent apps or packages:
 
 For apps, this is as easy as `meteor add modules`, or (even better) `meteor add ecmascript`, since the `ecmascript` package *implies* the `modules` package.
 
 For packages, you can enable `modules` by adding `api.use('modules')` to the `Package.onUse` or `Package.onTest` sections of your `package.js` file.
 
 Now, you might be wondering what good the `modules` package is without the `ecmascript` package, since `ecmascript` enables `import` and `export` syntax. By itself, the `modules` package provides the CommonJS `require` and `exports` primitives that may be familiar if you’ve ever written Node code, and the `ecmascript` package simply compiles `import` and `export` statements to CommonJS. The `require` and `export` primitives also allow Node modules to run within Meteor application code without modification. Furthermore, keeping `modules` separate allows us to use `require` and `exports` in places where using `ecmascript` is tricky, such as the implementation of the `ecmascript` package itself.
 
-While the `modules` package is useful by itself, we very much encourage using the `ecmascript` package (and thus `import` and `export`) instead of using `require` and `exports` directly. If you need convincing, here’s a presentation that explains the differences: http://benjamn.github.io/empirenode-2015
+While the `modules` package is useful by itself, we very much encourage using the `ecmascript` package (and thus `import` and `export`) instead of using `require` and `exports` directly. If you need convincing, here's a [presentation](http://benjamn.github.io/empirenode-2015) that explains the differences.
 
 ## Basic syntax
 
@@ -167,14 +184,87 @@ You can also use traditional CommonJS syntax with CoffeeScript.
 
 ## Modular application structure
 
+Use in your application `package.json` file the section `meteor`.
+
+> This is available since Meteor 1.7
+
+```json
+{
+  "meteor": {
+    "mainModule": {
+      "client": "client/main.js",
+      "server": "server/main.js"
+    }
+  }
+}
+```
+
+When specified, these entry points will define in which files Meteor is going to start the evaluation process for each architecture (client and server).
+
+This way Meteor is not going to eager load any other js files.
+
+There is also an architecture for the `legacy` client, which is useful if you want to load polyfills or other code for old browsers before importing the main module for the modern client.
+
+In addition to `meteor.mainModule`, the `meteor` section of `package.json` may also specify `meteor.testModule` to control which test modules are loaded by `meteor test` or `meteor test --full-app`:
+
+```json
+{
+  "meteor": {
+    "mainModule": {
+      "client": "client/main.js",
+      "server": "server/main.js"
+    },
+    "testModule": "tests.js"
+  }
+}
+```
+
+If your client and server test files are different, you can expand the testModule configuration using the same syntax as mainModule:
+
+```json
+{
+  "meteor": {
+    "mainModule": {
+      "client": "client/main.js",
+      "server": "server/main.js"
+    },
+    "testModule": {
+      "client": "client/tests.js",
+      "server": "server/tests.js"
+    }
+  }
+}
+```
+
+The same test module will be loaded whether or not you use the `--full-app` option. 
+
+Any tests that need to detect `--full-app` should check `Meteor.isAppTest`. 
+
+The module(s) specified by `meteor.testModule` can import other test modules at runtime, so you can still distribute test files across your codebase; just make sure you import the ones you want to run.
+
+To disable eager loading of modules on a given architecture, simply provide a mainModule value of false:
+
+```json
+{
+  "meteor": {
+    "mainModule": {
+      "client": false,
+      "server": "server/main.js"
+    }
+  }
+}
+```
+
+### Historic behind Modular application structure
+
+If you want to understand how Meteor works without `meteor.mainModule` on `package.json` keep reading this section, but we don't recommend this approach anymore.
+
 Before the release of Meteor 1.3, the only way to share values between files in an application was to assign them to global variables or communicate through shared variables like `Session` (variables which, while not technically global, sure do feel syntactically identical to global variables). With the introduction of modules, one module can refer precisely to the exports of any other specific module, so global variables are no longer necessary.
 
 If you are familiar with modules in Node, you might expect modules not to be evaluated until the first time you import them. However, because earlier versions of Meteor evaluated all of your code when the application started, and we care about backwards compatibility, eager evaluation is still the default behavior.
 
 If you would like a module to be evaluated *lazily* (in other words: on demand, the first time you import it, just like Node does it), then you should put that module in an `imports/` directory (anywhere in your app, not just the root directory), and include that directory when you import the module: `import {stuff} from './imports/lazy'`. Note: files contained by `node_modules/` directories will also be evaluated lazily (more on that below).
 
-Lazy evaluation will very likely become the default behavior in a future version of Meteor, but if you want to embrace it as fully as possible in the meantime, we recommend putting all your modules inside either `client/imports/` or `server/imports/` directories, with just a single entry point for each architecture: `client/main.js` and `server/main.js`. The `main.js` files will be evaluated eagerly, giving your application a chance to import modules from the `imports/` directories.
-
 ## Modular package structure
 
 If you are a package author, in addition to putting `api.use('modules')` or `api.use('ecmascript')` in the `Package.onUse` section of your `package.js` file, you can also use a new API called `api.mainModule` to specify the main entry point for your package:
