Create updates section (#5687)

Signed-off-by: Christopher Hakkaart <chris.hakkaart@seqera.io>
Signed-off-by: Ben Sherman <bentshermann@gmail.com>
Co-authored-by: Ben Sherman <bentshermann@gmail.com>

docs/developer/plugins.md

@@ -1,3 +1,4 @@
+(plugins-dev-page)=
 
 # Plugins
 

docs/dsl1.md

@@ -1,24 +1,12 @@
 (dsl1-page)=
 
-# Migrating from DSL 1
+# Migrating from DSL1
 
-In Nextflow version `22.03.0-edge`, DSL2 became the default DSL version. In version `22.12.0-edge`, DSL1 support was removed, and the Nextflow documentation was updated to use DSL2 by default. Users who are still using DSL1 should migrate their pipelines to DSL2 in order to use the latest versions of Nextflow. This page describes the differences between DSL1 and DSL2, and how to migrate to DSL2.
-
-In Nextflow versions prior to `22.03.0-edge`, you must enable DSL2 explicitly in order to use it. You can either set the feature flag in your pipeline script:
-
-```nextflow
-nextflow.enable.dsl=2
-```
-
-Or set the environment variable where you launch Nextflow:
-
-```bash
-export NXF_DEFAULT_DSL=2
-```
+In Nextflow version `22.03.0-edge`, DSL2 became the default DSL version. In version `22.12.0-edge`, DSL1 support was removed and the Nextflow documentation was updated to use DSL2 by default. Users who are still using DSL1 should migrate their pipelines to DSL2 to use the latest versions of Nextflow. This page describes the differences between DSL1 and DSL2 and how to migrate to DSL2.
 
 ## Processes and workflows
 
-In DSL1, a process definition is also the process invocation. Process inputs and outputs are connected to channels using `from` and `into`. Here is the {ref}`your-first-script` example written in DSL1:
+In DSL1, a process definition is also the process invocation. Process inputs and outputs are connected to channels using `from` and `into`. You can see a basic Nextflow script written in DSL1 here:
 
 ```nextflow
 nextflow.enable.dsl=1
@@ -53,44 +41,69 @@ result.view { it.trim() }
 
 To migrate this code to DSL2, you need to move all of your channel logic throughout the script into a `workflow` definition. Additionally, you must call each process explicitly, passing any input channels as arguments (instead of `from ...`) and receiving any output channels as return values (instead of `into ...`).
 
-Refer to the {ref}`workflow-page` page to learn how to define a workflow. The DSL2 version of the above script is duplicated here for your convenience:
+See {ref}`workflow-page` page to learn how to define a workflow.
 
-```{literalinclude} snippets/your-first-script.nf
-:language: nextflow
-```
+You can see the DSL1 Nextflow script from above written in DSL2 here:
 
-## Channel forking
+```nextflow
+params.str = 'Hello world!'
+
+process splitLetters {
+    output:
+    path 'chunk_*'
+
+    script:
+    """
+    printf '${params.str}' | split -b 6 - chunk_
+    """
+}
 
-In DSL1, a channel can be used as an input only once; to use a channel multiple times, the channel must be forked using the `into` operator.
+process convertToUpper {
+    input:
+    path x
 
-In DSL2, channels are automatically forked when connecting two or more consumers.
+    output:
+    stdout
 
-For example, this would not work in DSL1 but is not a problem in DSL2:
+    script:
+    """
+    cat $x | tr '[a-z]' '[A-Z]'
+    """
+}
+
+workflow {
+    splitLetters | flatten | convertToUpper | view { v -> v.trim() }
+}
+```
+
+## Channel forking
+
+In DSL1, a channel can be used as an input only once; to use a channel multiple times, the channel must be forked using the `into` operator. In DSL2, channels are automatically forked when connecting two or more consumers. For example:
 
 ```nextflow
 Channel
-    .from('Hello','Hola','Ciao')
-    .set{ cheers }
+    .of('Hello','Hola','Ciao')
+    .set { cheers }
 
 cheers
-    .map{ it.toUpperCase() }
+    .map { v -> v.toUpperCase() }
     .view()
 
 cheers
-    .map{ it.reverse() }
+    .map { v -> v.reverse() }
     .view()
 ```
 
-Similarly, process outputs can be consumed by multiple consumers automatically, which makes workflow scripts much easier to read and write.
+Similarly, in DSL2, process outputs can be consumed by multiple consumers automatically, which makes workflow scripts much easier to read and write.
 
 ## Modules
 
-In DSL1, the entire Nextflow pipeline must be defined in a single file (e.g. `main.nf`). This restriction becomes quite cumbersome as a pipeline becomes larger, and it hinders the sharing and reuse of pipeline components.
+In DSL1, the entire Nextflow pipeline must be defined in a single file. For example, `main.nf`. This restriction becomes cumbersome as a pipeline grows and hinders the sharing and reuse of pipeline components.
 
-DSL2 introduces the concept of "module scripts" (or "modules" for short), which are Nextflow scripts that can be "included" by other scripts. While modules are not essential to migrating to DSL2, nor are they mandatory in DSL2 by any means, modules can help you organize a large pipeline into multiple smaller files, and take advantage of modules created by others. Check out the {ref}`module-page` to get started.
+DSL2 introduces the concept of "module scripts" (or "modules" for short), which are Nextflow scripts that can be "included" by other scripts. While modules are not essential to migrating to DSL2, nor are they mandatory in DSL2, modules can help you organize a large pipeline into multiple smaller files and take advantage of modules created by others. See {ref}`module-page` to learn more about modules.
 
 :::{note}
-DSL2 scripts cannot exceed 64 KB in size. Large DSL1 scripts may need to be split into modules to avoid this limit.
+DSL2 scripts cannot exceed 64 KB in size. Split large DSL1 scripts into modules to avoid this limit.
 :::
 
 ## Deprecations
@@ -103,14 +116,13 @@ DSL2 scripts cannot exceed 64 KB in size. Large DSL1 scripts may need to be spli
 
 - The `mode flatten` option for process outputs is no longer available. Use the {ref}`operator-flatten` operator on the corresponding output channel instead.
 
-- Unqualified value and file elements in a tuple declaration are no longer allowed. Use an explicit `val` or `path` qualifier.
-
-  For example:
+- Unqualified value and file elements in a tuple declaration are no longer allowed. Use an explicit `val` or `path` qualifier. For example:
 
   ```nextflow
   process foo {
       input:
       tuple X, 'some-file.sam'
+
       output:
       tuple X, 'some-file.bam'
 
@@ -127,6 +139,7 @@ DSL2 scripts cannot exceed 64 KB in size. Large DSL1 scripts may need to be spli
   process foo {
       input:
       tuple val(X), path('some-file.sam')
+
       output:
       tuple val(X), path('some-file.bam')
 

docs/index.md

@@ -80,7 +80,6 @@ notifications
 secrets
 sharing
 vscode
-dsl1
 ```
 
 ```{toctree}
@@ -124,6 +123,16 @@ reference/channel
 reference/operator
 ```
 
+```{toctree}
+:hidden:
+:caption: Updates
+:maxdepth: 1
+
+updating-nextflow
+updating-syntax
+dsl1
+```
+
 ```{toctree}
 :hidden:
 :caption: Contributing

docs/install.md

@@ -2,11 +2,17 @@
 
 # Installation
 
+Nextflow can be used on any POSIX-compatible system (Linux, macOS, etc), and on Windows through [WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux). This page describes how to install Nextflow.
+
+:::{note}
+New versions of Nextflow are released regularly. See {ref}`updating-nextflow-page` for more information about Nextflow release cadence, how to update Nextflow, and how select your version of Nextflow.
+:::
+
 (install-requirements)=
 
 ## Requirements
 
-Nextflow can be used on any POSIX-compatible system (Linux, macOS, etc), and on Windows through [WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux). It requires Bash 3.2 (or later) and [Java 17 (or later, up to 23)](http://www.oracle.com/technetwork/java/javase/downloads/index.html) to be installed. You can see which version you have using the following command:
+Nextflow requires Bash 3.2 (or later) and [Java 17 (or later, up to 23)](http://www.oracle.com/technetwork/java/javase/downloads/index.html) to be installed. To see which version of Java you have, run the following command:
 
 ```{code-block} bash
 :class: copyable
@@ -17,7 +23,7 @@ java -version
 Support for Java versions prior to 17 was dropped.
 :::
 
-If you don't have a compatible version of Java installed in your computer, it is recommended that you install it through [SDKMAN!](https://sdkman.io/), and that you use the latest LTS version of Temurin. See [this website](https://whichjdk.com/) for more information.
+If you don't have a compatible version of Java installed, it is recommended that you install it through [SDKMAN!](https://sdkman.io/), and that you use the latest Long-Term-Support (LTS) version of Temurin. See [Which version of JDK should I use?](https://whichjdk.com/) for more information about different versions of Java.
 
 To install Java with SDKMAN:
 
@@ -50,15 +56,15 @@ To install Java with SDKMAN:
 
 Nextflow is distributed as a self-installing package, in order to make the installation process as simple as possible:
 
-1. Install Nextflow:
+To install Nextflow:
+
+1. Download Nextflow:
 
     ```{code-block} bash
     :class: copyable
     curl -s https://get.nextflow.io | bash
     ```
 
-    This will create the `nextflow` executable in the current directory.
-
     :::{tip}
     Set `export CAPSULE_LOG=none` to make the installation logs less verbose.
     :::
@@ -93,27 +99,12 @@ Nextflow is distributed as a self-installing package, in order to make the insta
     nextflow info
     ```
 
-## Updates
-
-With Nextflow installed in your environment, you can update to the latest version using the following command:
-
-```{code-block} bash
-:class: copyable
-nextflow self-update
-```
-
-You can also temporarily switch to a specific version of Nextflow with the `NXF_VER` environment variable. For example:
-
-```{code-block} bash
-:class: copyable
-NXF_VER=23.10.0 nextflow info
-```
-
 ## Seqera Platform
 
 You can launch workflows directly from [Seqera Platform](https://seqera.io/platform/) without installing Nextflow locally.
 
 Launching from Seqera Platform provides you with:
+
 - User-friendly launch interfaces.
 - Automated cloud infrastructure creation.
 - Organizational user management.
@@ -122,34 +113,11 @@ Launching from Seqera Platform provides you with:
 Seqera Cloud Basic is free for small teams. Researchers at qualifying academic institutions can apply for free access to Seqera Cloud Pro.
 See the [Seqera Platform documentation](https://docs.seqera.io/platform) for set-up information and tutorials to get started.
 
-## Stable and edge releases
-
-A *stable* version of Nextflow is released every six months, in the 4th and 10th month of each year.
-
-Additionally, an *edge* version is released on a monthly basis. The edge releases can be used to access the latest updates and experimental features.
-
-To use the latest edge release, set `NXF_EDGE=1` when updating:
-
-```{code-block} bash
-:class: copyable
-NXF_EDGE=1 nextflow self-update
-```
-
-You can also use `NXF_VER` to temporarily switch to any edge release. For example:
-
-```{code-block} bash
-:class: copyable
-NXF_VER=24.06.0-edge nextflow info
-```
-
 ## Standalone distribution
 
-The Nextflow standalone distribution (i.e. the `dist` distribution) consists of self-contained `nextflow` executable file
-that includes all the application dependencies for core functionalities, and it can run without downloading third parties
-libraries. This distribution is mainly useful for offline environments.
+The Nextflow standalone distribution (i.e. the `dist` release) is a self-contained `nextflow` executable that can run without needing to download core dependencies at runtime. This distribution is useful for offline environments, as well as building and testing Nextflow locally.
 
-Note however the support for cloud services e.g. AWS, Seqera Platform, Wave, etc. still require the download
-of the corresponding Nextflow plugins.
+The standalone distribution will still download core and third-party plugins as needed at runtime.
 
 To use the standalone distribution:
 

docs/reference/syntax.md

@@ -27,8 +27,8 @@ A Nextflow script may contain the following top-level declarations:
 
 - Shebang
 - Feature flags
-- Includes
-- Parameter definitions
+- Include declarations
+- Parameter declarations
 - Workflow definitions
 - Process definitions
 - Function definitions

docs/sharing.md

@@ -115,6 +115,8 @@ For example, shebang definitions `#!/usr/bin/python` and `#!/usr/local/bin/pytho
 ```
 :::
 
+(lib-directory)=
+
 #### The `lib` directory
 
 The `lib` directory can be used to add utility code or external libraries without cluttering the pipeline scripts. The `lib` directory in the Nextflow project root is added to the classpath by default. Classes defined in the `lib` directory will be available in pipeline scripts. Functions defined outside of classes will not be available in pipeline scripts.

docs/updating-nextflow.md

@@ -0,0 +1,62 @@
+(updating-nextflow-page)=
+
+# Updating Nextflow
+
+This page describes Nextflow release cadence, how to self-update Nextflow, and how select your version of Nextflow.
+
+## Releases
+
+A stable version of Nextflow is released in the 4th and 10th month of each year. A edge version of Nextflow is released on a monthly basis. The edge version can be used to access the latest updates and experimental features. 
+
+You can find an exhaustive list of releases and updates in the [Nextflow changelog](https://github.com/nextflow-io/nextflow/blob/master/changelog.txt).
+
+## Self-update
+
+To update to the latest stable release of Nextflow, run the `self-update` command:
+
+```{code-block} bash
+:class: copyable
+nextflow self-update
+```
+
+To use the latest edge release, set `NXF_EDGE=1` when you self-update Nextflow:
+
+```{code-block} bash
+:class: copyable
+NXF_EDGE=1 nextflow self-update
+```
+
+:::{warning}
+Nextflow will update its executable during the self-update process. The update can fail if the Nextflow executable is in a directory with restricted permissions.
+:::
+
+## Version selection
+
+The `NXF_VER` environment variable can be used to define which version of Nextflow to use. To switch to a specific version of Nextflow for a single run, set the `NXF_VER` environment variable in your execution command. For example:
+
+```{code-block} bash
+:class: copyable
+NXF_VER=23.10.0 nextflow info
+```
+
+To set a specific version of Nextflow for a terminal session, export the `NXF_VER` environment variable. For example:
+
+```{code-block} bash
+:class: copyable
+export NXF_VER=23.10.0
+```
+
+To set a specific version of Nextflow for your user profile, add the above `NXF_VER` export command to your shell configuration file, such as `~/.bashrc` or `~/.zshrc`, and restart your session.
+
+:::{tip}
+You can use `NXF_VER` to switch to an edge release. For example:
+
+```{code-block} bash
+:class: copyable
+NXF_VER=24.06.0-edge nextflow info
+```
+:::
+
+:::{warning}
+Nextflow will update its executable during the self-update process. The update can fail if the Nextflow executable is in a directory with restricted permissions.
+:::