Merge branch 'master' into master

Author: knolleary

about/releases/index.md

@@ -4,30 +4,27 @@ title: Release Plan
 slug: releases
 ---
 
-_Updated: 2021-10-21_
+_Updated: 2022-08-04_
 
 This plan is a guide for how the project plans to schedule upcoming releases, taking
 into account the release schedule of the underlying Node.js runtime.
 
 ![](release-plan.png)
 
 
-The active Node-RED stream (2.x) will get a new minor version release (for example, 2.1 ->  2.2)
-every three months. Maintenance releases (for example 2.1.0 -> 2.1.1) will continue
+The active Node-RED stream (3.x) will get a new minor version release (for example, 3.1 ->  3.2)
+every three months. Maintenance releases (for example 3.1.0 -> 3.1.1) will continue
 to happen as and when they are needed.
 
-At the end of April 2022, when Node 12.x reaches its end-of-life, we will publish
-Node-RED 3.x that will *drop* support for Node 12.
+At the end of April 2023, when Node 14.x reaches its end-of-life, we will publish
+Node-RED 4.x that will *drop* support for Node 14.
 
-The 2.x stream will then enter maintenance mode. It will only receive bug fixes
-and security updates. New features could get back-ported from 3.x if there was
+The 3.x stream will then enter maintenance mode. It will only receive bug fixes
+and security updates. New features could get back-ported from 4.x if there was
 a very good reason to do so as well as people available to do the work.
 
-The 3.x stream will continue in active development with a minor release every
-three months or so until April 2023 when Node 14.x reaches its end-of-life. We
-then publish Node-RED 4.x and the cycle continues. The 2.x stream will reach its
-end-of-life soon after the 4.x release. The exact timing of that will be something
-we will need to discuss further.
+The 4.x stream will continue in active development with a minor release every
+three months or so for a year, when the next major release is made.
 
 This proposal means:
 
@@ -37,13 +34,14 @@ This proposal means:
  - We have a plan that enables us to make potentially breaking changes once a year.
 
 
-Release | Initial     | Maintenance Start    | End-of-life
---------|-------------|----------------------|-----------------
-1.x     | 2019-09-30  | 2021-04-30           | 2022-06-30
-2.x     | 2021-04-30  | 2022-04-30           | 2023-06-30
-3.x     | 2022-04-30  | 2023-04-30           | 2024-06-30
+Release | Initial         | Maintenance Start    | End-of-life
+--------|-----------------|----------------------|-----------------
+1.x     | 2019-09-30      | 2021-04-30           | 2022-06-30
+2.x     | 2021-07-22      | 2022-07-14           | 2023-06-30
+3.x     | 2022-07-14      | *2023-04-30* *       | 2024-06-30
+4.x     | *2023-04-30* *  | *2024-04-30* *       | 2025-06-30
 
-_Dates are subject to change_
+_* Dates are subject to change_
 
 References:
  - [Blog post: Going beyond Node-RED 1.x](https://nodered.org/blog/2020/07/01/release-plans)

about/releases/release-plan.png

@@ -59,7 +59,9 @@ function:
 ```javascript
 let foo = env.get("FOO");
 ```
+
 ### Template node
+
 *Since [Node-RED 3.0](https://nodered.org/blog/2022/07/14/version-3-0-released#environment-variables-in-the-template-node)*
 
 The `template` node  can access environment variables using the syntax:
@@ -78,22 +80,61 @@ a subflow could be created to access the API and handle the response, using an
 environment variable to identify which type of record should be accessed. Individual
 instances of the Subflow can then be customised for those particular types.
 
+
+
 ### Flow/Group level environment variables
 
 *Since [Node-RED 2.1](https://nodered.org/blog/2021/10/21/version-2-1-released#flowgroup-level-environment-variables)*
 
 Environment variables can be set at the flow or group level. This is done in the appropriate tab in the edit dialog for the flow or group.
 
+### Accessing nested environment variables
+
+When accessing an environment variable in a subflow, Node-RED will search the
+subflow properties, then the flow containing the subflow (which could be a subflow
+itself).
+
+In some cases it is useful to access the 'parent' levels environment variables
+without reference the 'local' value. This can be achieved by prefixing the
+variable name with `$parent.`.
+
+
 ### Running as a service
+
 When Node-RED is running as a service having been installed using the provided [script](https://nodered.org/docs/getting-started/raspberrypi), it will not have access to environment variables that are defined only in the calling process. In this instance, environment variables can be defined in the settings file by adding:
-````
-process.env.FOO= 'World';
-````
+
+```
+process.env.FOO='World';
+```
+
 placed outside the `module.exports` section. Alternatively, variables can be defined as part of the `systemd` service by placing statements of the form
+
 ```
 ENV_VAR='foobar'
-````
-in a file named `environment` in the Node-RED user directory, `~/.node-red`.
+```
+in a file named `environment` within the Node-RED user directory, `~/.node-red`.
+
+
+### Built-In Environment Variables
+
+*Since Node-RED 2.2*
+
+Node-RED defines a set of environment variables for exposing information about the nodes, flows and groups.
+
+This information helps "locate" the node in your [workspace](/docs/user-guide/editor/workspace/index.md). Nodes in your workspace exist as part of a [flow](/docs/user-guide/editor/workspace/flows.md). Likewise, a node may (or may not) be part of a [group](/docs/user-guide/editor/workspace/groups.md). Nodes, flows and groups are each given unique IDs that are generated by Node-RED.
+
+Nodes, flows and groups all support the `name` property, which you can change when [editing properties](/docs/user-guide/editor/workspace/nodes.md#editing-node-properties).
+
+The following environment variables can be used to access this information for a given node:
+
+- `NR_NODE_ID` - the ID of the node
+- `NR_NODE_NAME` - the Name of the node
+- `NR_NODE_NAME` - the Path of the node. This represents a node's position in a flow.  It is `/` delimited IDs of the flow, enclosing subflows, and the node.
+- `NR_GROUP_ID` - the ID of the containing group
+- `NR_GROUP_NAME` - the Name of the containing group
+- `NR_FLOW_ID` - the ID of the flow the node is on
+- `NR_FLOW_NAME` - the Name of the flow the node is on
 
+Note that while the IDs generated by Node-RED are guaranteed to be unique, the names are not. If a node, flow or group does not have a given name, the corresponding environment variable will be an empty string. If a node is not part of a group, its group id environment variable will also return an empty string.