Cutlery/caddy
1
0
Fork 0
mirror of https://github.com/caddyserver/caddy.git synced 2025-07-09 03:04:57 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update instructions for new build server and website.

Matt Holt 2017-04-18 20:02:38 -06:00
parent 9cb957d6c2
commit 6de81e8640
1 changed files with 26 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
Publishing-a-Plugin-to-the-Download-Page.md

@ -2,69 +2,53 @@
This page describes how to publish your plugin to the [download page](https://caddyserver.com/download) on Caddy's website.
## Background
## Before you publish
Caddy's download page is powered by the Caddy build server. This build server has a file with a list of all the plugins and some information about them. Your job is to add your plugin to that list, after which maintainers will update the build server. (The current build server is temporary and will be replaced with a more robust, automated one in the future. This tutorial will change when we get to that point.)
Use this checklist to make sure your plugin is ready to be published:
## What you need to do
- [ ] **My plugin's license is compatible with [Caddy's license](https://github.com/mholt/caddy/blob/master/LICENSE.txt).** GPL and commercial-only licenses are not allowed at this time.
1. Read and agree to the terms and requirements
2. Write documentation for your plugin and submit it to the Caddy website
3. Submit a pull request to add your plugin to the build server
4. **Only if plugin is a Caddyfile directive:** Submit a pull request to the repository of the server type, adding your directive to the list
- [ ] **If my plugin adds any directives to the Caddyfile, I've submitted a pull request to the server type's repo to put it in the right order; and that change has been released.** New directives need to be known by the server type so they can be put in the right order. For example, the HTTP server's list of directives is in [httpserver/plugin.go](https://github.com/mholt/caddy/blob/729e4f0239528e1c2ac2f64207aef769564fc697/caddyhttp/httpserver/plugin.go#L434). Once your PR is merged, you should wait until that change is released, because the Download page only makes binaries from release versions. If you publish your plugin before your change is released, your users won't be able to use your directive even if your plugin is plugged in.
### 1. Terms and Requirements
- [ ] **Documentation is available in the plugin project's README or website.** Your plugin's documentation is not hosted on the Caddy website; make sure it is easy find, follow, and is accurate and complete. The only documentation for your plugin that goes on the Caddy website is a description and a few examples.
To add your package to the plugin registry, it must meet the following requirements, and you must agree to these terms.
- [ ] **This plugin is in its own repository.** Multiple plugins should not share a repo. This is required for building specific versions of your plugin; if two plugins share a repo but a build requires them at two different versions, that build will be impossible. Technically, two plugins _may_ share a repo, but only if they would never have disjoint versions, and we do not recommend this.
- The plugin name must one lowercase word (excepting brand names, which must be combined to appear as one lowercase word). It must be unique and differentiable from other directives, as well as clear and obvious what the directive does (not misleading). This is important to maintain consistency and make it easy for users. Choose carefully, since it cannot be changed except by rare exception.
- [ ] **My plugin is generally useful.** Plugins that can be useful to only one or two people are not a good fit for the Caddy website and may be removed.
- Project is and will remain actively maintained and updated. This means that any issues or pull requests are responded to within a reasonable amount of time by project owner(s) or collaborator(s), that security fixes are applied as soon as possible, and that the package effectively remains in a stable, working state.
- [ ] **My plugin and its dependencies do NOT require cgo.** Caddy and plugins are built by disabling cgo to ensure cross-platform compilation.
- Maintainer agrees to create and keep a page of documentation updated by submitting pull requests to the [caddyserver.com repository](https://github.com/caddyserver/caddyserver.com).
- [ ] **My plugin's functionality is unique.** The Caddy download page is not an app store or marketplace; we follow the "improve or remove" philosophy.
- The package must complement the goals of the Caddy project. Packages that are not in the best interest of the project or its users in general or which carry other implications may not be accepted. Similarly, packages that plug into the HTTP server should add functionality best provided by a web server. This can be a gray area, so if you're unsure, [ask](https://forum.caddyserver.com) before going to all the trouble.
- [ ] **I have tests for my plugin!** Passing tests are extremely important; your plugin cannot be deployed if it fails tests, and it must have tests. Tests must pass in unprivileged environments and within a reasonable amount of time.
- Packages that use or rely on free third-party services (which are only free) will be decided on a case-by-case basis.
- [ ] **My plugin is safe.** It does not cause harm to the system it is running on, and its code is written with care. (For example, it doesn't delete [all the files](https://github.com/valvesoftware/steam-for-linux/issues/3671) or [destroy root](https://github.com/systemd/systemd/issues/5644).)
- Packages that integrate with commercial services (including services with free plans/trials) may be decided based on sponsorship.
- [ ] **My plugin does not violate or interfere with Caddy's goals, values, or vision.** In other words, it doesn't spy on users, inject ads, break HTTPS, associate with DRM technology, etc. The plugin must be in the best interest of Caddy and its users.
- The functionality of a package must be unique among other registered packages and the Caddy core. This is not an app store. We follow the "improve or remove" philosophy.
- [ ] **I agree to actively maintain my plugin.** This means that any issues or pull requests are responded to within a reasonable amount of time by project owner(s) or collaborator(s), that security fixes are applied as soon as possible, that fixes/updates are deployed on occasion, and that the package effectively remains in a stable, working state.
- The package and its dependencies must not invoke cgo.
_Distribution on the Caddy website does not imply endorsement by the Caddy project or its author, maintainers, or contributors. Users assume all risks and you, the developer, are responsible for updates, security, and maintaining your own code. Plugins may be removed by the Caddy maintainers if they do not meet this criteria or for any other reason._
- The package must compile cross-platform.
## Listing your plugin
- Package must be under test using the standard Go `testing` package rather than third-party testing dependencies. Tests should not take more than a few seconds to run.
1. If you haven't already, [create a Developer Portal account](https://caddyserver.com/account/register). Verify your email address, then log in.
- The project license must be compatible with the main Caddy project license.
2. Click "Register Plugin":
<img src="https://i.imgur.com/WwGrGoA.png" width="200">
- Distribution from the Caddy website does not imply endorsement by the Caddy project or its author, maintainers, or contributors. Users assume all risks and you are responsible for updates, security, and maintaining your own code.
3. Follow the instructions for each field. **Note:** Put each plugin in its own repository; versioning becomes difficult/impossible if different plugins are in the same repository.
4. Click "Next". Your repo will be downloaded in an attempt to find the plugin you are publishing. Select it in the list.
### 2. Documentation
5. Fill out the rest of the fields; a good description and examples are vital to the success of your plugin! Make the first sentence of the description really count.
Since we'll be offering your plugin on our download page, you need to take a few minutes and write up some documentation. You can have docs as a README or wiki with your repository, of course, but we still need them on the Caddy website for the benefit of users.
6. When you submit the form, your plugin will be deployed. A deploy consists of `go vet` checks, cross-platform build checks, and `go test -race`. Everything must pass before it is available for download, but your plugin will appear on the [docs pages](https://caddyserver.com/docs) immediately.
Please [submit a pull request to caddyserver/caddyserver.com](https://github.com/caddyserver/caddyserver.com/pulls) with a page of documentation.
Deploys take a while, even 10-15 minutes. You will be notified via email (or in your account if you disabled email notifications) with the result of the deploy. Do not deploy again until the current deploy finishes.
Docs can be written in Markdown except where Caddyfile syntax highlighting or other special formatting is required; for those portions, use clean HTML. We reserve the right to change or update or fix your docs at any time, but we also ask that you keep them up-to-date. Neglected docs can be grounds for removal from the download page.
## Updating your plugin
### 3. Register Plugin
At any time, you may log in to the Developer Portal and update your plugin's description, examples, and links. You can also deploy new versions at will. Please keep your plugin up-to-date! Users can see how long ago the last update was. Also please ensure that the examples are concise, useful, informative, and accurate at all times.
Once docs have been submitted, it's time to open a PR to register your plugin. By doing this, you assert agreement to the terms above.
Simply [add your plugin to registry.go](https://github.com/caddyserver/buildsrv/blob/master/features/registry.go) in the buildsrv repository. You may follow the example of plugins that came before yours. The order in that list does not matter, but we group similar plugins next to each other.
Once we merge that PR and update the build server, your plugin will become available. You may continue pushing to master on your repository without breaking the build server, as it only updates when you tell us to update it. Make sure not to forget that!
### 4. Register Directive
**Only necessary if your plugin adds a directive to the Caddyfile.** Since directives have to be executed in the right order, it is your job to determine the right order for your directive and submit a pull request to that repository, adding it.
For example, to add a directive for the HTTP server Caddyfile, submit a PR to mholt/caddy with your directive [added to the list of directives](https://github.com/mholt/caddy/blob/4ff46ad447c22346a4b636a51caff305fec7001b/caddyhttp/httpserver/plugin.go#L332).
Repositories for Caddy server types:
- [HTTP](https://github.com/mholt/caddy)
- [DNS](https://github.com/miekg/coredns)
Thank you for publishing a plugin! Hope you enjoy being a part of the community.