diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md index c2dd9cb72502fb..185d3d15bbed66 100644 --- a/docs/maintainers/maintainer-guide.md +++ b/docs/maintainers/maintainer-guide.md @@ -52,6 +52,28 @@ At this time, the following helpers are deprecated: Ideally, portfiles should be short, simple, and as declarative as possible. Remove any boiler plate comments introduced by the `create` command before submitting a PR. +### Ports must not be path dependent + +Ports must not change their behavior based on which ports are already installed in a form that would change which contents that port installs. For example, given: + +``` +> vcpkg install a +> vcpkg install b +> vcpkg remove a +``` + +and + +``` +> vcpkg install b +``` + +the files installed by `b` must be the same, regardless of influence by the previous installation of `a`. This means that ports must not try to detect whether something is provided in the installed tree by another port before taking some action. A specific and common cause of such "path dependent" behavior is described below in "When defining features, explicitly control dependencies." + +### Unique port attribution rule + +In the entire vcpkg system, no two ports a user is expected to use concurrently may provide the same file. If a port tries to install a file already provided by another file, installation will fail. If a port wants to use an extremely common name for a header, for example, it should place those headers in a subdirectory rather than in `include`. + ## Features ### Do not use features to implement alternatives