From 9b02054e432ae3e9c7ada0236b1b2e304e2b4dab Mon Sep 17 00:00:00 2001
From: Billy O'Neal <bion@microsoft.com>
Date: Thu, 19 Jan 2023 16:59:05 -0800
Subject: [PATCH] Add a new-port checklist to the new PR template. (#27447)

* Add a new-port checklist to the new PR template.

I have observed many people tend to "tune out" our current pull request template, including maintainers, who don't even look at the content and sometimes miss important things people are trying to tell us. To that end, I would like to replace it with something more useful, including things for people submitting the most common kinds of PRs to check.

* Apply fixes suggested by @vicroms and @PhoebeHui
---
 .github/pull_request_template.md          | 36 ++++++++++++++++-------
 docs/examples/adding-an-explicit-usage.md | 36 +++++++++++++++++++++++
 2 files changed, 62 insertions(+), 10 deletions(-)
 create mode 100644 docs/examples/adding-an-explicit-usage.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 9253eadcb2..738ec027cf 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,15 +1,31 @@
-**Describe the pull request**
+<!-- If your PR fixes issues, please note that here by adding "Fixes #NNNNNN." for each fixed issue on separate lines. -->
 
-- #### What does your PR fix?
-  Fixes #...
+<!-- If you are still working on the PR, open it as a Draft: https://github.blog/2019-02-14-introducing-draft-pull-requests/ -->
 
-- #### Which triplets are supported/not supported? Have you updated the [CI baseline](https://github.com/microsoft/vcpkg/blob/master/scripts/ci.baseline.txt)?
-  <all / linux, windows, ...>, <Yes/No>
+<!-- If this PR updates an existing port, please uncomment and fill out this checklist:
 
-- #### Does your PR follow the [maintainer guide](https://github.com/microsoft/vcpkg/blob/master/docs/maintainers/maintainer-guide.md)?
-  `Your answer`
+- [ ] Changes comply with the [maintainer guide](https://github.com/microsoft/vcpkg/blob/master/docs/maintainers/maintainer-guide.md)
+- [ ] SHA512s are updated for each updated download
+- [ ] The "supports" clause reflects platforms that may be fixed by this new version
+- [ ] Any fixed [CI baseline](https://github.com/microsoft/vcpkg/blob/master/scripts/ci.baseline.txt) entries are removed from that file.
+- [ ] Any patches that are no longer applied are deleted from the port's directory.
+- [ ] The version database is fixed by rerunning `./vcpkg x-add-version --all` and committing the result.
+- [ ] Only one version is added to each modified port's versions file.
 
-- #### If you have added/updated a port: Have you run `./vcpkg x-add-version --all` and committed the result?
-  <Yes / I am still working on this PR>
+END OF PORT UPDATE CHECKLIST (delete this line) -->
 
-**If you are still working on the PR, open it as a Draft: https://github.blog/2019-02-14-introducing-draft-pull-requests/**
+<!-- If this PR adds a new port, please uncomment and fill out this checklist:
+
+- [ ] Changes comply with the [maintainer guide](https://github.com/microsoft/vcpkg/blob/master/docs/maintainers/maintainer-guide.md)
+- [ ] The name of the port matches an existing name for this component on https://repology.org/ if possible, and/or is strongly associated with that component on search engines.
+- [ ] Optional dependencies are resolved in exactly one way. For example, if the component is built with CMake, all `find_package` calls are REQUIRED, are satisfied by `vcpkg.json`'s declared dependencies, or disabled with [CMAKE_DISABLE_FIND_PACKAGE_Xxx](https://cmake.org/cmake/help/latest/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
+- [ ] The versioning scheme in `vcpkg.json` matches what upstream says.
+- [ ] The license declaration in `vcpkg.json` matches what upstream says.
+- [ ] The installed as the "copyright" file matches what upstream says.
+- [ ] The source code of the component installed comes from an authoritative source.
+- [ ] The generated "usage text" is accurate. See docs/examples/adding-an-explicit-usage.md for context.
+- [ ] The version database is fixed by rerunning `./vcpkg x-add-version --all` and committing the result.
+- [ ] Only one version is in the new port's versions file.
+- [ ] Only one version is added to each modified port's versions file.
+
+END OF NEW PORT CHECKLIST (delete this line) -->
diff --git a/docs/examples/adding-an-explicit-usage.md b/docs/examples/adding-an-explicit-usage.md
new file mode 100644
index 0000000000..57fb89cb43
--- /dev/null
+++ b/docs/examples/adding-an-explicit-usage.md
@@ -0,0 +1,36 @@
+## How to: Add an explicit usage file to a port.
+
+`vcpkg` generates usage text for customers who install particular ports, if the customer names that
+specific port. For example:
+
+```
+$> vcpkg install zlib:x64-windows
+Computing installation plan...
+The following packages will be built and installed:
+  * vcpkg-cmake[core]:x64-windows -> 2022-09-26
+    zlib[core]:x64-windows -> 1.2.12#2
+Additional packages (*) will be modified to complete this operation.
+Detecting compiler hash for triplet x64-windows...
+Restored 2 package(s) from C:\Users\bion\AppData\Local\vcpkg\archives in 77.46 ms. Use --debug to see more details.
+Installing 1/2 vcpkg-cmake:x64-windows...
+Elapsed time to handle vcpkg-cmake:x64-windows: 10.32 ms
+Installing 2/2 zlib:x64-windows...
+Elapsed time to handle zlib:x64-windows: 20.89 ms
+Total elapsed time: 2.747 s
+
+The package zlib is compatible with built-in CMake targets:
+
+    find_package(ZLIB REQUIRED)
+    target_link_libraries(main PRIVATE ZLIB::ZLIB)
+```
+
+If there is no explicit usage installed by the port, vcpkg will generate default usage text by
+inspecting with the port installs. If the default usage text is suboptimal, it can be overridden by
+a port installing a file named "usage" in its "share" directory.
+
+1. Create a file named `usage` in the port directory, with the content you want displayed.
+2. To `portfile.cmake`, add
+```
+file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
+```
+3. Update the port-version and rerun `vcpkg x-add-version` if necessary.