Skip to content

Update plugins documentation #6033

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 24 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
c487aaa
Update plugins docs
christopher-hakkaart Apr 24, 2025
a046331
Add run command example
christopher-hakkaart Apr 27, 2025
989af21
Update links
christopher-hakkaart Apr 28, 2025
5471abc
Add repo link
christopher-hakkaart Apr 28, 2025
3dfb945
Add Trace observers note
christopher-hakkaart Apr 28, 2025
e254b63
Revise defined registry
christopher-hakkaart May 5, 2025
5a6e4d9
Add plugin create documentation
christopher-hakkaart May 6, 2025
0a5f013
Merge branch 'master' into pr/christopher-hakkaart/6033
bentsherman May 6, 2025
9053ca9
Fix plugin config scope example
bentsherman May 6, 2025
ce87361
Only support registry
christopher-hakkaart May 7, 2025
d68a8d7
Merge branch 'docs-plugins' of https://github.com/christopher-hakkaar…
christopher-hakkaart May 7, 2025
2bb3960
cleanup
bentsherman May 7, 2025
e153d96
Remove registry URL
bentsherman May 7, 2025
1be0336
cleanup migration guide
bentsherman May 7, 2025
7bfc78d
cleanup gradle plugin guide
bentsherman May 7, 2025
93691b8
Merge branch 'master' into docs-plugins
christopher-hakkaart May 7, 2025
fa2dc0f
Unlist h3 headings
christopher-hakkaart May 7, 2025
ea585de
Merge branch 'master' into pr/christopher-hakkaart/6033
bentsherman May 9, 2025
aa87a22
Replace nf-hello example with plugin template
bentsherman May 9, 2025
758b818
Cleanup private beta notes
bentsherman May 9, 2025
e0866bc
Add transition plan for legacy index -> registry
bentsherman May 9, 2025
5ab28f6
Merge branch 'master' into pr/christopher-hakkaart/6033
bentsherman May 10, 2025
de7aaa1
Apply suggestions from code review
bentsherman May 10, 2025
d011970
Unlist timeline subheadings
bentsherman May 10, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 12 additions & 16 deletions docs/gradle-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,25 +65,21 @@ To run unit tests:

## Packaging, uploading, and publishing a plugin

The Gradle plugin for Nextflow plugins simplifies publishing your plugin.
The Gradle plugin for Nextflow plugins simplifies publishing your plugin to the Nextflow Plugin Registry.

To package, upload, and publish your plugin:
:::{note}
The Nextflow Plugin Registry is currently available as private beta technology. Contact [info@nextflow.io](mailto:info@nextflow.io) to learn how to get access.
:::

1. Fork the [Nextfow plugins index repository](https://github.com/nextflow-io/plugins).
2. In the plugin root directory, open `build.gradle` and ensure that:
* `github.repository` matches the plugin repository.
* `github.indexUrl` matches your fork of the plugins index repository.
3. Create a file named `$HOME/.gradle/gradle.properties` and add the following:
To package, upload, and publish your plugin to the Nextflow Plugin Registry:

1. Create a file named `$HOME/.gradle/gradle.properties`, where `$HOME` is your home directory.
2. Add the following properties:

```bash
github_username=<GITHUB_USERNAME>
github_access_token=<GITHUB_ACCESS_TOKEN>
github_commit_email=<GITHUB_EMAIL>
pluginRegistry.accessToken=<REGISTRY_ACCESS_TOKEN>
```

Replace the following:
* `GITHUB_USERNAME`: your GitHub username granting access to the plugin repository.
* `GITHUB_ACCESS_TOKEN`: your GitHub access token with permission to upload and commit changes to the plugin repository.
* `GITHUB_EMAIL`: your email address associated with your GitHub account.
4. Run `make release`.
5. Create a pull request against the [Nextfow plugins index repository](https://github.com/nextflow-io/plugins) from your fork.
Replace <REGISTRY_ACCESS_TOKEN> with your plugin registry access token.

3. Run `make release`.
21 changes: 10 additions & 11 deletions docs/migrating-gradle-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,14 @@ The Gradle plugin for Nextflow plugins simplifies and standardizes the developme

The Gradle plugin is versioned and published to the [Gradle Plugin Portal](https://plugins.gradle.org/), allowing developers to manage it like any other dependency. As the plugin ecosystem evolves, this Gradle plugin will enable easier maintenance and adoption of ongoing improvements to the Nextflow plugin framework.

### Nextflow plugin registry
### Nextflow Plugin Registry

The Nextflow plugin registry is a centralized repository of assembled plugins. It hosts an index of plugin metadata that supports plugin discovery, accessibility, and version tracking. The registry is integrated with the Nextflow runtime. Nextflow will automatically locate and download configured plugins.

:::{note}
The Nextflow Plugin Registry is currently available as private beta technology. Contact [info@nextflow.io](mailto:info@nextflow.io) to learn how to get access.
:::

## Impact on users and developers

The impact of the Gradle plugin for Nextflow plugins differs for plugin users and developers.
Expand Down Expand Up @@ -57,7 +61,7 @@ To migrate an existing Nextflow plugin:
```groovy
// Plugins
plugins {
id 'io.nextflow.nextflow-plugin' version '0.0.1-alpha3'
id 'io.nextflow.nextflow-plugin' version '0.0.1-alpha4'
}

// Dependencies (optional)
Expand All @@ -79,13 +83,10 @@ To migrate an existing Nextflow plugin:
'<EXTENSION_POINT>'
]

publishing {
github {
repository = '<GITHUB_REPOSITORY>'
userName = project.findProperty('github_username')
authToken = project.findProperty('github_access_token')
email = project.findProperty('github_commit_email')
indexUrl = '<GITHUB_INDEX_URL>'
publishing {
registry {
url = 'https://nf-plugins-registry.dev-tower.net/api'
authToken = project.findProperty('pluginRegistry.accessToken')
}
}
}
Expand All @@ -99,8 +100,6 @@ To migrate an existing Nextflow plugin:
- `PROVIDER`: Your name or organization—for example, `acme`.
- `CLASS_NAME`: Your plugin class name—for example, `acme.plugin.MyPlugin`.
- `EXTENSION_POINT`: Your extension point identifiers that the plugin will implement or expose—for example, `acme.plugin.MyFactory`.
- `GITHUB_REPOSITORY`: Your GitHub plugin repository name—for example, `nextflow-io/nf-plugin-template`.
- `GITHUB_INDEX_URL`: The URL of your fork of the plugins index repository—for example, [`https://github.com/nextflow-io/plugins/blob/main/plugins.json`](https://github.com/nextflow-io/plugins/blob/main/plugins.json).

5. Replace the contents of `Makefile` with the following:

Expand Down
2 changes: 1 addition & 1 deletion docs/plugins/developing-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ The Gradle plugin is versioned and published to the [Gradle Plugin Portal](https

```nextflow
plugins {
id 'io.nextflow.nextflow-plugin' version '0.0.1-alpha3'
id 'io.nextflow.nextflow-plugin' version '0.0.1-alpha4'
}
```

Expand Down
2 changes: 1 addition & 1 deletion docs/plugins/example-nf-hello.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ It also includes several classes that demonstrate different plugin functionality
The `nf-hello` plugin can be configured via nextflow configuration files or at runtime. For example:

```bash
nextflow run hello -plugins nf-hello@0.5.0,nf-amazon@2.9.0
nextflow run hello -plugins nf-hello@0.5.0
```

See the [nf-hello plugin repository](https://github.com/nextflow-io/nf-hello/tree/gradle-plugin-example) for the plugin source code.