diff --git a/Publishing-a-Plugin-to-the-Download-Page.md b/Publishing-a-Plugin-to-the-Download-Page.md new file mode 100644 index 0000000..b8b092a --- /dev/null +++ b/Publishing-a-Plugin-to-the-Download-Page.md @@ -0,0 +1,66 @@ +**[Join the Caddy Community Forum](https://forum.caddyserver.com) to chat with other Caddy developers!** + +This page describes how to publish your plugin to the [download page](https://caddyserver.com/download) on Caddy's website. + +## Background + +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.) + +## What you need to do + +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 + +### 1. Terms and Requirements + +To add your package to the plugin registry, it must meet the following requirements, and you must agree to these terms. + +- 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. + +- 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. + +- 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). + +- 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. + +- Packages that use or rely on free third-party services (which are only free) will be decided on a case-by-case basis. + +- Packages that integrate with commercial services (including services with free plans/trials) may be decided based on sponsorship agreements. + +- 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. + +- The package must not use cgo and must be cross-platform compatible. + +- 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. + +- The project license must be compatible with the main Caddy project license. + + +### 2. Documentation + +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. + +Please [submit a pull request to caddyserver/caddyserver.com](https://github.com/caddyserver/caddyserver.com/pulls) with a page of documentation. Remember to add a link to your new page in the nav. + +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. + +### 3. Register Plugin + +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) \ No newline at end of file