| ======================= | |
| Vendored library policy | |
| ======================= | |
| To simplify Bleach development, we're now vendoring certain libraries that | |
| we use. | |
| Vendored libraries must follow these rules: | |
| 1. Vendored libraries must be pure Python--no compiling. | |
| 2. Source code for the libary is included in this directory. | |
| 3. License must be included in this repo and in the Bleach distribution. | |
| 4. Requirements of the library become requirements of Bleach. | |
| 5. No modifications to the library may be made. | |
| Adding/Updating a vendored library | |
| ================================== | |
| Way to vendor a library or update a version: | |
| 1. Update ``vendor.txt`` with the library, version, and hash. You can use | |
| `hashin <https://pypi.org/project/hashin/>`_. | |
| 2. Remove all old files and directories of the old version. | |
| 3. Run ``pip_install_vendor.sh`` and check everything it produced in including | |
| the ``.dist-info`` directory and contents. | |
| 4. Update the bleach minor version in the next release. | |
| Reviewing a change involving a vendored library | |
| =============================================== | |
| Way to verify a vendored library addition/update: | |
| 1. Pull down the branch. | |
| 2. Delete all the old files and directories of the old version. | |
| 3. Run ``pip_install_vendor.sh``. | |
| 4. Run ``git diff`` and verify there are no changes. | |
| NB: the current ``vendor.txt`` was generated with pip 20.2.3, which might be necessary to reproduce the dist-info | |
| Removing/Unvendoring a vendored library | |
| ======================================= | |
| A vendored library might be removed for any of the following reasons: | |
| * it violates the vendoring policy (e.g. an incompatible license | |
| change) | |
| * a suitable replacement is found | |
| * bleach has the resources to test and QA new bleach releases against | |
| multiple versions of the previously vendored library | |
| To unvendor a library: | |
| 1. Remove the library and its hashes from ``vendor.txt``. | |
| 2. Remove library files and directories from this directory. | |
| 3. Run ``install_vendor.sh`` and check the previously vendored library including | |
| the ``.dist-info`` directory and contents is not installed. | |
| 4. Update the bleach minor version in the next release. | |