Skip to content

Commit a52a4a3

Browse files
matreimatrei
committed
Update readme for the new index
1 parent 45aaa26 commit a52a4a3

1 file changed

Lines changed: 113 additions & 33 deletions

File tree

‎README.md‎

Lines changed: 113 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,120 @@
11
# Grails Plugin Page Data Source
2-
This repository hosts the data used by the [Grails Plugin Page](https://www.grails.org/plugins.html) to list and display plugin information.
2+
3+
This repository hosts the data used by the [Grails Plugin Page](https://grails.apache.org/plugins.html) to list and display plugin information.
4+
5+
## Plugin Data Structure
6+
7+
Plugins are organized in the `grails-plugins/` directory using a hierarchical structure based on Maven coordinates. Each plugin is represented by a YAML file containing its metadata and version information.
8+
9+
### Directory Organization
10+
11+
Plugins are organized by their Maven groupId. The directory structure mirrors the groupId with the YAML file named as the artifactId:
12+
```
13+
grails-plugins (root directory, not part of the coordinates)
14+
├───cloud
15+
│ └───wondrify
16+
│ └───asset-pipeline-grails.yml
17+
└───org
18+
├───apache
19+
│ └───grails
20+
│ ├───grails-async.yml
21+
│ └───grails-cache.yml
22+
└───grails
23+
└───plugins
24+
├───grails-mail.yml
25+
└───grails-logical-delete.yml
26+
```
327

428
## Adding Your Plugin to the Grails Plugin Page
29+
530
To have your plugin listed on the Grails Plugin Page, follow these steps:
6-
7-
1. Open the [grails-plugins.json](grails-plugins.json) file in this repository.
8-
2. Add a new entry with the following structure to the **end of the JSON list**:
9-
10-
```json
11-
{
12-
"bintrayPackage": {
13-
"name": "Your Plugin Name",
14-
"repo": "your-plugin-repo-name",
15-
"owner": "your-github-username",
16-
"desc": "A concise description of your plugin",
17-
"labels": [
18-
"relevant-label",
19-
"check-existing-labels"
20-
],
21-
"licenses": [
22-
"Apache-2.0"
23-
],
24-
"issueTrackerUrl": "https://github.com/your-github-username/your-plugin-repo/issues",
25-
"latestVersion": "1.0",
26-
"updated": "2024-12-25T04:00:40.855Z",
27-
"systemIds": [
28-
"your.plugin.maven:coords"
29-
],
30-
"vcsUrl": "https://github.com/your-github-username/your-plugin-repo-name"
31-
},
32-
"documentationUrl": "https://github.com/your-github-username/your-plugin-repo-name#readme",
33-
"mavenMetadataUrl": "https://repo1.maven.org/maven2/your/plugin/maven/coords/maven-metadata.xml"
34-
}
31+
32+
1. **Fork this repository**
33+
34+
2. **Create the directory structure** – If needed, create the appropriate directory structure based on your Maven groupId:
35+
- For `com.example.plugins` → `grails-plugins/com/example/plugins/`
36+
- For `org.myorg` → `grails-plugins/org/myorg/`
37+
- The directory structure must match your groupId exactly
38+
39+
3. **Create a YAML file** for your plugin named `<artifactId>.yml` with the following structure:
40+
```yaml
41+
name: Your Plugin Name # Try to not use the word "Grails" here, it is implied and not helpful
42+
desc: A concise description of your plugin # Maven coordinates in format groupId:artifactId
43+
coords: com.example:my-plugin # groupId:artifactId
44+
owner: Your name or organization # for example, your GitHub username
45+
vcs: https://github.com/your-github-username/your-plugin-repo-name # URL to your plugin's GitHub repository
46+
docs: https://github.com/your-github-username/your-plugin-repo-name#readme # URL to your plugin's documentation
47+
maven-repo: https://repo1.maven.org/maven2 # Or the repo where your plugin is published
48+
labels: # List of relevant labels (see the plugin page for label conventions)
49+
- relevant-label
50+
- check-existing-labels
51+
- do-not-put-grails-here
52+
licenses: # List of license identifiers (e.g., Apache-2.0, MIT, GPL-3.0)
53+
- Apache-2.0
54+
```
55+
56+
4. **Place the file** in the appropriate directory:
57+
- File name format: `<artifactId>.yml` (use the artifact ID from your coords, not the plugin name)
58+
- Example paths:
59+
- `grails-plugins/com/example/plugins/my-artifact-id.yml` (if coords is `com.example.plugins:my-artifact-id`)
60+
- `grails-plugins/org/myorg/my-plugin.yml` (if coords is `org.myorg:my-plugin`)
61+
62+
5. **Create a Pull Request** with your changes.
63+
64+
6. **Wait for approval** - A member of the Grails team will review and merge your PR. Once merged, your plugin will appear on the Grails Plugin Page.
65+
66+
## Versions
67+
68+
A "versions" property will be automatically generated and kept up to date in your YAML-file. This property is a list detailing plugin releases, including their version, release date, and compatible Grails version. Crucially, the "grailsVersion" within each release entry is sourced directly from your plugin's Grails Plugin Descriptor. This data is vital for users to figure out compatibility with their application's Grails version, **so please verify its accuracy before publishing**.
69+
70+
```yaml
71+
versions:
72+
- version: 4.0.1
73+
date: 2026-02-11T12:58:35Z
74+
grailsVersion: 7.0.0 > *
75+
- version: 4.0.0
76+
date: 2025-10-16T16:08:47Z
77+
grailsVersion: 7.0.0 > *
3578
```
36-
3. Create a **Pull Request** with your changes.
37-
4. Wait for approval. Once merged, your plugin will appear on the Grails Plugin Page.
3879

3980
## Updating Your Plugin
40-
When you release a new version of your plugin, the system will automatically generate a Pull Request to update your plugin's entry in this repository. A member of the Grails team will review and merge the update.
81+
82+
Once your plugin's YAML file is accepted and merged into this repository, the system will periodically scan for new plugin versions and update the `versions` list accordingly. You do not need to manually update the YAML file when you release a new version of your plugin.
83+
84+
However, if the automatically scanned version information is somehow incorrect, you can manually edit the YAML file to correct it. This is useful if the `grailsVersion` or other metadata from your plugin descriptor needs to be adjusted. Any version already present in the YAML file will not be updated automatically.
85+
86+
If the plugin has been published to multiple maven coordinates or repositories over time, these versions can still be aggregated in the YAML-file by adding override properties `coords` and/or `maven-repo` to the version items.
87+
88+
```yaml
89+
# Example from org.grails.plugins:grails-mail
90+
version:
91+
- version: 5.0.0
92+
date: 2025-06-10T18:09:54Z
93+
grailsVersion: 7.0.0 > *
94+
- version: 4.0.2
95+
date: 2025-06-18T05:56:58Z
96+
grailsVersion: 6.0.0 > *
97+
coords: org.grails.plugins:mail
98+
- version: 4.0.1
99+
date: 2025-04-11T06:13:16Z
100+
grailsVersion: 6.0.0 > *
101+
coords: org.grails.plugins:mail
102+
- version: 4.0.0
103+
date: 2024-04-30T07:30:11Z
104+
grailsVersion: 6.0.0 > *
105+
coords: org.grails.plugins:mail
106+
- version: 3.0.0
107+
date: 2021-02-24T05:35:23Z
108+
grailsVersion: 3.0 > *
109+
coords: org.grails.plugins:mail
110+
maven-repo: https://repo.grails.org/plugins
111+
```
112+
113+
114+
## Deprecating Plugins
115+
116+
If the development of a plugin is discontinued or if it for other reasons is not relevant anymore, you can add a `deprecated` property to the YAML file, with a description of why it is deprecated. This information will be displayed on the [Grails Plugin Page](https://grails.apache.org/plugins.html) entry.
117+
118+
## Removing Plugins
119+
120+
If the plugin should no longer be displayed in the plugin index, you can remove the YAML file, and it will be removed from the index on the next indexing operation.

0 commit comments

Comments
 (0)