Submitting to the PopClip Extensions Directory from your own repo

submit-extension.md

author
Nick Moore

PopClip Directory Submission

All extensions on the directory need to be hosted as public repositories on GitHub.

The directory server downloads and stores your repository contents every time you create a git tag. It only does this once for every tag. This ensures that the contents served for a specific version can never change.

The server needs to be informed whenever a new tag is created. For this purpose, we use GitHub webhooks.

The server processes your extension source files. Behind the scenes, it will extract metadata from the Config file and sign and zip the extension. Do not submit zipped popclipextz file; it will not work.

Prepare the Source Files

Required Fields

All extensions MUST have all of the following fields in the Config:

• name: Extension name. Prefer a short name, e.g., Instapaper, not Send to Instapaper.
• identifier: Unique identifier. This is the primary identifier of your extension in the database and can never be changed.
• description: A concise description that will be shown in the directory next to the extension name.
• popclipVersion: Specify the integer PopClip version, e.g., 4586. Typically, this should be the version you have been using while testing your extension.

Submitting an extension with any of these fields missing will fail.

Limits

• No more than 100 files per extension package.
• No individual file larger than 1 MiB.
• Total size of all files no more than 2 MiB.

Readme and Demo

An optional readme file called readme.md (not case-sensitive) will be detected automatically. Markdown format.

An optional demo file called demo.mp4 or demo.gif will be detected automatically. Max file size is 1 MiB. Prefer mp4 for quality and smaller file size. The demo file will be automatically excluded from the final extension.

Hidden Files

Any files or folders starting with . or _ will automatically be excluded from the final extension.

Credits

The directory will automatically add the source repo link to the directory listing. Add any additional credits information in the Readme file. Do not put "Credits" in the Config file. (You can if you want, but it will be ignored.)

Changelog

Please include a changelog at the footer of the Readme file. Suggested format:

## Changelog

- <date>: Updated xyz.
- <date>: Initial release.

License

Optional: Put LICENSE/LICENSE.txt in the repo root. If you don't specify a license, I will apply the MIT License by default.

Set Up Webhook

Webhook URL

The webhook URL is as follows:

https://api.pilotmoon.com/webhooks/gh?include=<path or glob>&versionPrefix=<prefix>

The query parameters are:

• include (required): Path to the package source folder(s) for the extension(s) being submitted. This can be a single path or a glob pattern. You can repeat the include parameter to specify more than one. If the repo root itself is the package source folder, put include=..
• versionPrefix (optional): If the tag is using a prefix, specify it here. For example, v. The prefix will be stripped off the tag to get the version number. Any tags without the prefix will be ignored.

Example:

This is the webhook URL I use for pilotmoon/PopClip-Extensions:

https://api.pilotmoon.com/webhooks/gh?include=source/*.popclipext&versionPrefix=v

Add the Webhook to the Repo

1. Navigate to the repository you want to add.
2. Go to the Settings tab.
3. Click on the Webhooks tab.
4. Click on the Add webhook button.
5. Enter the webhook URL (above) in the payload URL field.
6. Content type: doesn't matter.
7. Secret: leave blank.
8. Select Let me select individual events.
9. Select only the Branch or tag creation event.
10. Press Add webhook.

Submit Release

Tag the Release

When you have finished preparing the extension(s) for submission, tag the repository.

The version number must be made of one or more non-negative integers, without leading zeros, separated by dots.

✅ Valid: 1, 1.6, 5076.95.0.

❌ Not valid: 1.00, 1.7-beta2.

Version number must be higher than the last submitted version.

If the tag has a prefix, e.g., v1.45, make sure to specify this in the versionPrefix parameter.

Push to GitHub

Push the repo to GitHub.

Depending on your git config, you may need to push it with the --tags parameter, e.g., git push origin main --tags.

Check Results

In the Webhook settings, check "Recent deliveries" -> "Body" and look for the "Remote log:" link. Open this link in a browser. This will have the results of the submission.

If successful, you will see something like:

[0:00:01.566]
All nodes processed
The include directive matched 189 paths.
There were changes to 1 of those paths.
There were 1 successful submissions and 0 failed submissions.

Successful submissions:

✅ source/Gladys.popclipext
Gladys
5n6ehh 156 com.andrewford.popclip.extension.gladystext

Failed submissions:


Done

END

If the submission fails, make the necessary changes and submit a new tag.

(In rare cases, the error may be internal, e.g., GitHub API network error. In this case, you can send the tag again using the "Redeliver" option in GitHub webhook settings under recent deliveries.)

Submissions are not automatically published. I will review them.