From 2b358dc980e59cbf5cbe8a1bd053419935c5ae4c Mon Sep 17 00:00:00 2001 From: Mateusz Mandera Date: Tue, 21 Mar 2023 12:11:48 +0100 Subject: [PATCH] docs: Document how to use a self-modified dependency with Zulip in dev. As explained in the doc, sometimes you want to test your changes to a dependency WITH Zulip without waiting for upstream merge and release. --- requirements/README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/requirements/README.md b/requirements/README.md index 49f1568584..de8b6fad37 100644 --- a/requirements/README.md +++ b/requirements/README.md @@ -18,3 +18,32 @@ Steps to update a lock file, e.g. to update ipython from 5.3.0 to latest version 2. Increase `PROVISION_VERSION` in `version.py`. 3. Run `./tools/provision` to install the new deps and test them. 4. Commit your changes. + +## Testing custom modifications of a dependency + +When working on Zulip, sometimes it is necessary to also make +modifications to a dependency (either to add a feature that we will +rely on, or to fix a bug that needs to be fixed for the intended +changes to work in Zulip) - with the idea that eventually they will be +merged upstream and included in an official release. + +That process can take time however, and sometimes it'd be good to be +able to create and test your Zulip changes on top of changes to the +upstream package, without waiting for the potentially lengthy code +review and release process of the upstream dependency. + +You can do this forking the upstream project, making the changes on a +branch in your fork, and then replacing the package's entry in +`dev.in` or `prod.in` with an appropriate GitHub link to the branch +with your modifications. The files have various examples of how this +should be done, but essentially you will add an entry looking like +this: + +``` +https://github.com///archive/.zip#egg===+git +``` + +After that, you can follow the above process involving +`./tools/update-locked-requirements` and the following steps to have +the modified package installed in your dev environment, where it can +be used for testing.