10 files changed, 493 insertions, 4 deletions
diff --git a/docs/index.md b/docs/index.md
index cde241e92..5d83b5804 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -19,6 +19,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 
 - [Control files](maintainers/control-files.md)
 - [Portfile functions](maintainers/portfile-functions.md)
+- [Maintainer Guidelines](maintainers/maintainer-guide.md)
 
 ### Specifications
 
diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md
index ac4afa265..03bfa113a 100644
--- a/docs/maintainers/control-files.md
+++ b/docs/maintainers/control-files.md
@@ -43,16 +43,27 @@ The port version.
 
 This field is an alphanumeric string that may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bit strings and are only evaluated for equality.
 
-By convention, if a portfile is modified without incrementing the "upstream" version, a `-#` is appended to create a unique version string.
+For tagged-release ports, we follow the following convention:
 
-Some projects do not have named releases.  In these cases use the date of the version   do not have labeled releases, in these cases use the date of the last commit in `YYYY-MM-DD` format.  See the `abseil` port as an example.
+1. If the port follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
+2. If the port includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
+3. If the port has been modified, we append a `-N` to distinguish the versions: `1.2.1-4`
+
+For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
+
+For example, given:
+1. The latest commit was made on 2019-04-19
+2. The current version string is `2019-02-14-1`
+3. Today's date is 2019-06-01.
+
+Then if you update the source version today, you should give it version `2019-06-01`. If you need to make a change which doesn't adjust the source version, you should give it version `2019-02-14-2`.
 
 Example:
 ```no-highlight
 Version: 1.0.5-2
 ```
 ```no-highlight
-Version: 2019-3-21
+Version: 2019-03-21
 ```
 
 #### Description
diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
new file mode 100644
index 000000000..0baa45a02
--- /dev/null
+++ b/docs/maintainers/maintainer-guide.md
@@ -0,0 +1,178 @@
+# Maintainer Guidelines and Policies
+
+This document lists a set of policies that you should apply when adding or updating a port recipe. It is intended to serve the role of [Debian's Policy Manual](https://www.debian.org/doc/debian-policy/), [Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and [Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).
+
+## PR Structure
+
+### Make separate Pull Requests per port
+
+Whenever possible, separate changes into multiple PR's. This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.
+
+### Avoid trivial changes in untouched files
+
+For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand. However, if you need to modify the file for the primary purpose of the PR (updating the library), then obviously beneficial changes like fixing typos are appreciated!
+
+### Check names against other repositories
+
+A good service to check many at once is [Repology](https://repology.org/). If the library you are adding could be confused with another one, consider renaming to make it clear.
+
+### Use GitHub Draft PRs
+
+GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge. Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.
+
+More information about GitHub Draft PRs: https://github.blog/2019-02-14-introducing-draft-pull-requests/
+
+## Portfiles
+
+### Avoid deprecated helper functions
+
+At this time, the following helpers are deprecated:
+
+1. `vcpkg_extract_archive()` should be replaced by `vcpkg_extract_archive_ex()`
+2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. `vcpkg_from_github()`)
+3. `vcpkg_build_msbuild()` should be replaced by `vcpkg_install_msbuild()`
+
+### Avoid excessive comments in portfiles
+
+Ideally, portfiles should be short, simple, and as declarative as possible. Remove any helper comments introduced by the `create` command before submitting a PR.
+
+## Build Techniques
+
+### Do not use vendored dependencies
+
+Do not use embedded copies of libraries. All dependencies should be split out and packaged separately so they can be updated and maintained.
+
+### Prefer using CMake
+
+When multiple buildsystems are available, prefer using CMake. Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.
+
+Examples: [abseil](../../ports/abseil/portfile.cmake)
+
+### Choose either static or shared binaries
+
+By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`, however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:
+
+```cmake
+string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
+string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)
+
+vcpkg_configure_cmake(
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
+        -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
+)
+```
+
+### When defining features, explicitly control dependencies
+
+When defining a feature that captures an optional dependency, ensure that the dependency will not be used accidentally when the feature is not explicitly enabled. For example:
+
+```cmake
+set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
+if("zlib" IN_LIST FEATURES)
+    set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
+endif()
+
+vcpkg_configure_cmake(
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
+)
+```
+
+Note that `ZLIB` in the above is case-sensitive. See the [cmake documentation](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) for more details.
+
+## Versioning
+
+### Follow common conventions for the `Version:` field
+
+See our [CONTROL files document](control-files.md#version) for a full explanation of our conventions.
+
+### Update the `Version:` field in the `CONTROL` file of any modified ports
+
+Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes.
+
+Our convention for this field is to append a `-N` to the upstream version when changes need to be made.
+
+For Example:
+
+- Zlib's package version is currently `1.2.1`.
+- You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile.
+- You should update the `Version:` field in the control file to `1.2.1-1`.
+
+See our [CONTROL files document](control-files.md#version) for a full explanation of our conventions.
+
+## Patching
+
+### Prefer options over patching
+
+It is preferable to set options in a call to `vcpkg_configure_xyz()` over patching the settings directly.
+
+Common options that allow avoiding patching:
+1. [MSBUILD] `<PropertyGroup>` settings inside the project file can be overridden via `/p:` parameters
+2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)
+3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overriden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)
+
+### Minimize patches
+
+When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional.
+
+This helps to keep the size of the vcpkg repository down as well as improves the likelihood that the patch will apply to future code versions.
+
+### Do not implement features in patches
+
+The purpose of patching in vcpkg is to enable compatibility with compilers, libraries, and platforms. It is not to implement new features in lieu of following proper Open Source procedure (submitting an Issue/PR/etc).
+
+## Do not build tests/docs/examples by default
+
+When submitting a new port, check for any options like `BUILD_TESTS` or `WITH_TESTS` or `POCO_ENABLE_SAMPLES` and ensure the additional binaries are disabled. This minimizes build times and dependencies for the average user.
+
+Optionally, you can add a `test` feature which enables building the tests, however this should not be in the `Default-Features` list.
+
+## Enable existing users of the library to switch to vcpkg
+
+### Do not add `CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS`
+
+Unless the author of the library is already using it, we should not use this CMake functionality because it interacts poorly with C++ templates and breaks certain compiler features. Libraries that don't provide a .def file and do not use __declspec() declarations simply do not support shared builds for Windows and should be marked as such with `vcpkg_check_linkage(ONLY_STATIC_LIBRARY)`.
+
+### Do not rename binaries outside the names given by upstream
+
+This means that if the upstream library has different names in release and debug (libx versus libxd), then the debug library should not be renamed to `libx`. Vice versa, if the upstream library has the same name in release and debug, we should not introduce a new name.
+
+Important caveat:
+- Static and shared variants often should be renamed to a common scheme. This enables consumers to use a common name and be ignorant of the downstream linkage. This is safe because we only make one at a time available.
+
+Note that if a library generates CMake integration files (`foo-config.cmake`), renaming must be done through patching the CMake build itself instead of simply calling `file(RENAME)` on the output archives/LIBs.
+
+Finally, DLL files on Windows should never be renamed post-build because it breaks the generated LIBs.
+
+## Useful implementation notes
+
+### Portfiles are run in Script Mode
+
+While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core CMake language constructs, portfiles run in "Script Mode", whereas `CMakeLists.txt` files run in "Build Mode" (unofficial term). The most important difference between these two modes is that "Script Mode" does not have a concept of "Target" -- any behaviors that depend on the "target" machine (`CMAKE_CXX_COMPILER`, `CMAKE_EXECUTABLE_SUFFIX`, `CMAKE_SYSTEM_NAME`, etc) will not be correct.
+
+Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`).
+
+Finally, portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:
+
+```no-highlight
++----------------------------+       +------------------------------------+
+| CMake.exe                  |       | CMake.exe                          |
++----------------------------+       +------------------------------------+
+| Triplet file               | ====> | Toolchain file                     |
+| (x64-windows.cmake)        |       | (scripts/buildsystems/vcpkg.cmake) |
++----------------------------+       +------------------------------------+
+| Portfile                   | ====> | CMakeLists.txt                     |
+| (ports/foo/portfile.cmake) |       | (buildtrees/../CMakeLists.txt)     |
++----------------------------+       +------------------------------------+
+```
+
+To determine the host in a portfile, the standard CMake variables are fine (`CMAKE_HOST_WIN32`).
+
+To determine the target in a portfile, the vcpkg triplet variables should be used (`VCPKG_CMAKE_SYSTEM_NAME`).
+
+See also our [triplet documentation](../users/triplets.md) for a full enumeration of possible settings.
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index f159f7f64..b98d89192 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -6,12 +6,14 @@
 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
 - [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
 - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
+- [vcpkg\_check\_features](vcpkg_check_features.md)
 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)
 - [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
 - [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
+- [vcpkg\_execute\_build\_process](vcpkg_execute_build_process.md)
 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
 - [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)
 - [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)
diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md
new file mode 100644
index 000000000..46ee9051a
--- /dev/null
+++ b/docs/maintainers/vcpkg_check_features.md
@@ -0,0 +1,71 @@
+# vcpkg_check_features
+
+Check if one or more features are a part of the package installation.
+
+## Usage
+```cmake
+vcpkg_check_features(
+    <feature1> <output_variable1>
+    [<feature2> <output_variable2>]
+    ...
+)
+```
+
+`vcpkg_check_features` accepts a list of (feature, output_variable) pairs. If a feature is specified, the corresponding output variable will be set as `ON`, or `OFF` otherwise. The syntax is similar to the `PROPERTIES` argument of `set_target_properties`.
+
+`vcpkg_check_features` will create a variable `FEATURE_OPTIONS` in the parent scope, which you can pass as a part of `OPTIONS` argument when calling functions like `vcpkg_config_cmake`:
+```cmake
+vcpkg_config_cmake(
+    SOURCE_PATH ${SOURCE_PATH}
+    PREFER_NINJA
+    OPTIONS
+        -DBUILD_TESTING=ON
+        ${FEATURE_OPTIONS}
+)
+```
+
+## Notes
+```cmake
+vcpkg_check_features(<feature> <output_variable>)
+```
+can be used as a replacement of:
+```cmake
+if(<feature> IN_LIST FEATURES)
+    set(<output_variable> ON)
+else()
+    set(<output_variable> OFF)
+endif()
+```
+
+However, if you have a feature that was checked like this before:
+```cmake
+if(<feature> IN_LIST FEATURES)
+    set(<output_variable> OFF)
+else()
+    set(<output_variable> ON)
+endif()
+```
+then you should not use `vcpkg_check_features` instead. [```oniguruma```](https://github.com/microsoft/vcpkg/blob/master/ports/oniguruma/portfile.cmake), for example, has a feature named `non-posix` which is checked with:
+```cmake
+if("non-posix" IN_LIST FEATURES)
+    set(ENABLE_POSIX_API OFF)
+else()
+    set(ENABLE_POSIX_API ON)
+endif()
+```
+and by replacing these code with:
+```cmake
+vcpkg_check_features(non-posix ENABLE_POSIX_API)
+```
+is totally wrong.
+
+`vcpkg_check_features` is supposed to be called only once. Otherwise, the `FEATURE_OPTIONS` variable set by a previous call will be overwritten.
+
+## Examples
+
+* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
+* [xsimd](https://github.com/microsoft/vcpkg/blob/master/ports/xsimd/portfile.cmake)
+* [xtensor](https://github.com/microsoft/vcpkg/blob/master/ports/xtensor/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)
diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
index 200d358ae..b78ef54d9 100644
--- a/docs/maintainers/vcpkg_configure_cmake.md
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -7,6 +7,8 @@ Configure CMake for Debug and Release builds of a project.
 vcpkg_configure_cmake(
     SOURCE_PATH <${SOURCE_PATH}>
     [PREFER_NINJA]
+    [DISABLE_PARALLEL_CONFIGURE]
+    [NO_CHARSET_FLAG]
     [GENERATOR <"NMake Makefiles">]
     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
@@ -26,6 +28,11 @@ Disables running the CMake configure step in parallel.
 
 This is needed for libraries which write back into their source directory during configure.
 
+### NO_CHARSET_FLAG
+Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`.
+
+This is needed for libraries that set their own source code's character set.
+
 ### GENERATOR
 Specifies the precise generator to use.
 
diff --git a/docs/maintainers/vcpkg_execute_build_process.md b/docs/maintainers/vcpkg_execute_build_process.md
new file mode 100644
index 000000000..d5b3593d9
--- /dev/null
+++ b/docs/maintainers/vcpkg_execute_build_process.md
@@ -0,0 +1,36 @@
+# vcpkg_execute_build_process
+
+Execute a required build process
+
+## Usage
+```cmake
+vcpkg_execute_build_process(
+    COMMAND <cmd> [<args>...]
+    [NO_PARALLEL_COMMAND <cmd> [<args>...]]
+    WORKING_DIRECTORY </path/to/dir>
+    LOGNAME <log_name>)
+)
+```
+## Parameters
+### COMMAND
+The command to be executed, along with its arguments.
+
+### NO_PARALLEL_COMMAND
+Optional parameter which specifies a non-parallel command to attempt if a
+failure potentially due to parallelism is detected.
+
+### WORKING_DIRECTORY
+The directory to execute the command in.
+
+### LOGNAME
+The prefix to use for the log files.
+
+This should be a unique name for different triplets so that the logs don't
+conflict when building multiple at once.
+
+## Examples
+
+* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_execute_build_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)
diff --git a/docs/maintainers/vcpkg_extract_source_archive_ex.md b/docs/maintainers/vcpkg_extract_source_archive_ex.md
index 92c90b296..8f525c3ce 100644
--- a/docs/maintainers/vcpkg_extract_source_archive_ex.md
+++ b/docs/maintainers/vcpkg_extract_source_archive_ex.md
@@ -25,7 +25,7 @@ The full path to the archive to be extracted.
 This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
 
 ### REF
-A friendly name that will be used instead of the filename of the archive.
+A friendly name that will be used instead of the filename of the archive.  If more than 10 characters it will be truncated.
 
 By convention, this is set to the version number or tag fetched
 
diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md
index 57a2bf75a..b868ea418 100644
--- a/docs/maintainers/vcpkg_find_acquire_program.md
+++ b/docs/maintainers/vcpkg_find_acquire_program.md
@@ -24,6 +24,7 @@ The current list of programs includes:
 - MESON
 - NASM
 - NINJA
+- NUGET
 - YASM
 - ARIA2 (Downloader)
 
diff --git a/docs/specifications/ports-overlay.md b/docs/specifications/ports-overlay.md
new file mode 100644
index 000000000..d486cfe19
--- /dev/null
+++ b/docs/specifications/ports-overlay.md
@@ -0,0 +1,182 @@
+# Ports Overlay (Jun 19, 2019)
+
+
+## 1. Motivation
+
+### A. Allow users to override ports with alternate versions
+
+It's a common scenario for `vcpkg` users to keep specific versions of libraries to use in their own projects. The current recommendation for users is to fork `vcpkg`'s repository and create tags for commits containing the specific versions of the ports they want to use.
+
+This proposal adds an alternative to solve this problem. By allowing `vcpkg` users to specify additional locations in their file system containing ports for:
+
+  * older or newer versions of libraries,
+  * modified libraries, or
+  * libraries not available in `vcpkg`.
+
+These locations will be searched when resolving port names during package installation, and override ports in `<vcpkg-root>/ports`.
+
+### B. Allow users to keep unmodified upstream ports
+
+Users will be able to keep unmodified versions of the ports shipped with `vcpkg` and update them via `vcpkg update` and `vcpkg upgrade` without having to solve merge conflicts.
+
+
+## 2. Other design concerns
+
+* Allow a set of `vcpkg` commands to optionally accept additional paths to be used when searching for ports.
+* Additional paths must take precedence when resolving names of ports to install.
+* Allow users to specify multiple additional paths.
+* Provide a simple disambiguation mechanism to resolve ambiguous port names.
+* After resolving a port name, the installation process has to work the same as for ports shipped by `vcpkg`.
+* This **DOES NOT ENABLE MULTIPLE VERSIONS** of a same library to be **INSTALLED SIDE-BY-SIDE**.
+
+
+## 3. Proposed solution
+
+This document proposes allowing additional locations to search for ports during package installation that will override and complement the set of ports provided by `vcpkg` (ports under the `<vcpkg_root>/ports` directory).`
+
+A new option `--overlay-ports` will be added to the `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, `vcpkg export`, and `vcpkg depend-info` commands to specify additional paths containing ports. 
+
+From a user experience perspective, a user expresses interest in adding additional lookup locations by passing the `--overlay-ports` option followed by a path to:
+
+* an individual port (directory containing a `CONTROL` file),
+  * `vcpkg install sqlite3 --overlay-ports="C:\custom-ports\sqlite3"`
+
+* a directory containing ports,
+  * `vcpkg install sqlite3 --overlay-ports=\\share\org\custom-ports`
+
+* a file listing paths to the former two.
+  > NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
+  
+  * `vcpkg install sqlite3 --overlay-ports=..\port-repos.txt`
+
+    _port-repos.txt_
+    
+    ```
+    .\experimental-ports\sqlite3
+    C:\custom-ports
+    \\share\team\custom-ports
+    \\share\org\custom-ports
+    ```
+    *Relative paths inside this file are resolved relatively to the file's location. In this case a `experimental-ports` directory should exist at the same level as the `port-repos.txt` file.*
+
+_NOTE: It is not the goal of this document to discuss library versioning or project dependency management solutions, which require the ability to install multiple versions of a same library side-by-side._ 
+
+### Multiple additional paths 
+
+Users can provide multiple additional paths by repeating the `--overlay-ports` option.
+
+```
+vcpkg install sqlite3 
+    --overlay-ports="..\experimental-ports\sqlite3" 
+    --overlay-ports="C:\custom-ports" 
+    --overlay-ports="\\share\team\custom-ports
+```
+
+### Overlaying ports
+
+Port name resolution follows the order in which additional paths are specified, with the first match being selected for installation, and falling back to `<vcpkg-root>/ports` if the port is not found in any of the additional paths.
+
+No effort is made to compare version numbers inside the `CONTROL` files, or to determine which port contains newer or older files.
+
+### Examples
+
+Given the following directory structure:
+
+  ```
+  team-ports/
+  |-- sqlite3/
+  |---- CONTROL
+  |-- rapidjson/
+  |---- CONTROL
+  |-- curl/
+  |---- CONTROL
+
+  my-ports/
+  |-- sqlite3/
+  |---- CONTROL
+  |-- rapidjson/
+  |---- CONTROL
+
+  vcpkg
+  |-- ports/
+  |---- <upstream ports>
+  |-- vcpkg.exe
+  |-- preferred-ports.txt
+  ```
+* #### Example #1:
+
+  Running:
+
+  ```
+  vcpkg/vcpkg.exe install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports
+  ```
+
+  Results in `my-ports/sqlite3` getting installed as that location appears first in the command line arguments.
+
+* #### Example #2:
+  
+  A specific version of a port can be given priority by adding its path first in the list of arguments:
+
+  ```
+  vcpkg/vcpkg.exe install sqlite3 rapidjson curl 
+      --overlay-ports=my-ports/rapidjson 
+      --overlay-ports=vcpkg/ports/curl
+      --overlay-ports=team-ports
+  ```
+
+  Installs:
+    * `sqlite3` from `team-ports/sqlite3`
+    * `rapidjson` from `my-ports/rapidjson`
+    * `curl` from `vcpkg/ports/curl`
+
+* #### Example #3:
+
+  > NOTE: Reading paths from a text file is not available in the current implementation, some revisions to this part of the specification are being made and will be implemented in a future date.
+  
+  Given the content of `preferred-ports.txt` as:
+
+  ```
+  ./ports/curl
+  /my-ports/rapidjson
+  /team-ports
+  ```
+
+  A location can be appended or prepended to those included in `preferred-ports.txt` via the command line, like this:
+
+  ```
+  vcpkg/vcpkg.exe install sqlite3 curl --overlay-ports=my-ports --overlay-ports=vcpkg/preferred-ports.txt
+  ```
+
+  Which results in `my-ports/sqlite3` and `vcpkg/ports/curl` getting installed.
+
+
+## 4. Proposed User experience
+
+### i. User wants to preserve an older version of a port
+
+Developer Alice and her team use `vcpkg` to acquire **OpenCV** and some other packages. She has even contributed many patches to add features to the **OpenCV 3** port in `vcpkg`. But, one day, she notices that a PR to update **OpenCV** to the next major version has been merged. 
+
+Alice wants to update some packages available in `vcpkg`. Unfortunately, updating her project to use the latest **OpenCV** is not immediately possible. 
+
+Alice creates a private GitHub repository and checks in the set of ports that she wants to preserve. Then provides her teammates with the link to clone her private ports repository.
+
+```
+mkdir vcpkg-custom-ports
+cd vcpkg-custom-ports
+git init 
+cp -r %VCPKG_ROOT%/ports/opencv .
+git add .
+git commit -m "[opencv] Add OpenCV 3 port"
+git remote add origin https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
+git push -u origin master
+```
+
+Now her team is able to use: 
+
+```
+git clone https://github.com/<Alice's GitHub username>/vcpkg-custom-ports.git
+vcpkg update --overlay-ports=./vcpkg-custom-ports
+vcpkg upgrade --no-dry-run --overlay-ports=./vcpkg-custom-ports
+``` 
+
+to upgrade their packages and preserve the old version of **OpenCV** they require.