Merge pull request #6 from nextflow-io/docs-clarification

Docs clarification
nextflow-io · Apr 22, 2024 · 3e298ed · 3e298ed
2 parents c200f24 + 9bc1826
commit 3e298ed
Show file tree

Hide file tree

Showing 3 changed files with 84 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -6,6 +6,9 @@
 
 ## Introduction
 
+> [!IMPORTANT]
+> nf-schema is the new version of the now deprecated [nf-validation](https://github.com/nextflow-io/nf-validation). Please follow the [migration guide](https://nextflow-io.github.io/nf-schema/latest/migration_guide/) to migrate your code to this new version.
+
 This [Nextflow plugin](https://www.nextflow.io/docs/latest/plugins.html#plugins) provides a number of functions that can be included into a Nextflow pipeline script to work with parameter and sample sheet schema. Using these functions you can:
 
 - 📖 Print usage instructions to the terminal (for use with `--help`)
@@ -22,7 +25,7 @@ Declare the plugin in your Nextflow pipeline configuration file:
 
 ```groovy title="nextflow.config"
 plugins {
-  id 'nf-schema'
+  id 'nf-schema@2.0.0'
 }
 ```
 

diff --git a/docs/index.md b/docs/index.md
@@ -11,4 +11,10 @@ description: Nextflow plugin for sample sheet validation
 
 ==}
 
---8<-- "README.md:6:"
+!!! info
+
+    nf-schema is the new version of the now deprecated [nf-validation](https://github.com/nextflow-io/nf-validation). Please follow the [migration guide](https://nextflow-io.github.io/nf-schema/latest/migration_guide/) to migrate your code to this new version.
+
+## Introduction
+
+--8<-- "README.md:11:"
diff --git a/docs/migration_guide.md b/docs/migration_guide.md
@@ -23,6 +23,37 @@ A full list of changes can be found in the [changelog](https://github.com/nextfl
 
 ## Updating your pipeline
 
+Updating your pipeline can be done in a couple simple steps.
+
+### Updating the name and version of the plugin
+
+The name and the version of the plugin should be updated from `nf-validation` to `[email protected]`:
+
+=== "nf-validation"
+
+    ```groovy
+    plugins {
+        id '[email protected]'
+    }
+    ```
+
+=== "nf-schema"
+
+    ```groovy
+    plugins {
+        id '[email protected]'
+    }
+    ```
+
+Additionally, all includes from `nf-validation` should be updated to `nf-schema`. This can easily be done with the following command:
+
+```bash
+find . -type f -name "*.nf" -exec sed -i -e "s/from 'plugin\/nf-validation'/from 'plugin\/nf-schema'/g" -
+e 's/from "plugin\/nf-validation"/from "plugin\/nf-schema"/g' {} +
+```
+
+### Updating the JSON schema files
+
 If you aren't using any special features in your schemas, you can simply update your `nextflow_schema.json` file using the following command:
 
 ```bash
@@ -33,10 +64,16 @@ This will replace the old schema draft specification (`draft-07`) by the new one
 
 !!! note
 
-    Repeat this command for every JSON schema you use in your pipeline. e.g. for the default samplesheet schema in nf-core pipelines:
-    `bash sed -i -e 's/http:\/\/json-schema.org\/draft-07\/schema/https:\/\/json-schema.org\/draft\/2020-12\/schema/g' -e 's/definitions/defs/g' assets/schema_input.json `
+    Repeat this command for every JSON schema used in your pipeline. e.g. for the default samplesheet schema in nf-core pipelines:
+    `bash sed -i -e 's/http:\/\/json-schema.org\/draft-07\/schema/https:\/\/json-schema.org\/draft\/2020-12\/schema/g' -e 's/definitions/defs/g' assets/schema_input.json`
+
+!!! warning
 
-Next you should update the `.fromSamplesheet` channel factory to the `samplesheetToList` function. Following tabs shows the difference between the versions:
+    This will not update changes to special fields in the schema, see the [guide](#updating-special-keywords-in-json-schemas) for special JSON schema keywords on how to update these
+
+### Update the samplesheet conversion
+
+The `.fromSamplesheet` channel factory should be converted to the `samplesheetToList` function. Following tabs shows how to use the function to get the same effect as the channel factory:
 
 === "nf-validation"
 
@@ -56,6 +93,39 @@ Next you should update the `.fromSamplesheet` channel factory to the `sampleshee
 
     This change was necessary to make it possible for pipelines to be used as pluggable workflows. This also enables the validation and conversion of files generated by the pipeline.
 
+### Updating configuration
+
+The configuration parameters have been converted to a Nextflow configuration option. You can now access these options using the `validation` config scope:
+
+```groovy
+validation.<option> = <value>
+```
+
+OR
+
+```groovy
+validation {
+    <option1> = <value1>
+    <option2> = <value2>
+}
+```
+
+See this table for an overview of what the new configuration options are for the old parameters:
+
+| Old parameter                                         | New config option(s)                                                             |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `params.validationMonochromeLogs = <boolean>`         | `validation.monochromeLogs = <boolean>`                                          |
+| `params.validationLenientMode = <boolean>`            | `validation.lenientMode = <boolean>`                                             |
+| `params.validationFailUnrecognisedParams = <boolean>` | `validation.failUnrecognisedParams = <boolean>`                                  |
+| `params.validationShowHiddenParams = <boolean>`       | `validation.showHiddenParams = <boolean>`                                        |
+| `params.validationIgnoreParams = <string>`            | `validation.defaultIgnoreParams = <list>` and `validation.ignoreParams = <list>` |
+
+!!! note
+
+    `defaultIgnoreParams` is meant to be used by pipeline developers to set the parameters which should always be ignored. `ignoreParams` is meant for the pipeline user to ignore certain parameters.
+
+## Updating special keywords in JSON schemas
+
 If you are using any special features in your schemas, you will need to update your schemas manually. Please refer to the [JSON Schema draft 2020-12 release notes](https://json-schema.org/draft/2020-12/release-notes) and [JSON schema draft 2019-09 release notes](https://json-schema.org/draft/2019-09/release-notes) for more information.
 
 However here are some guides to the more common migration patterns:
@@ -185,34 +255,3 @@ When you use `dependentRequired` in your schemas, you should update it like this
         }
     }
     ```
-
-### Updating configuration
-
-The configuration parameters have been converted to a Nextflow configuration option. You can now access these options using the `validation` config scope:
-
-```groovy
-validation.<option> = <value>
-```
-
-OR
-
-```groovy
-validation {
-    <option1> = <value1>
-    <option2> = <value2>
-}
-```
-
-See this table for an overview of what the new configuration options are for the old parameters
-
-| Old parameter                                         | New config option(s)                                                             |
-| ----------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `params.validationMonochromeLogs = <boolean>`         | `validation.monochromeLogs = <boolean>`                                          |
-| `params.validationLenientMode = <boolean>`            | `validation.lenientMode = <boolean>`                                             |
-| `params.validationFailUnrecognisedParams = <boolean>` | `validation.failUnrecognisedParams = <boolean>`                                  |
-| `params.validationShowHiddenParams = <boolean>`       | `validation.showHiddenParams = <boolean>`                                        |
-| `params.validationIgnoreParams = <string>`            | `validation.defaultIgnoreParams = <list>` and `validation.ignoreParams = <list>` |
-
-!!! note
-
-    `defaultIgnoreParams` is meant to be used by pipeline developers to set the parameters which should always be ignored. `ignoreParams` is meant for the pipeline user to ignore certain parameters.