about summary refs log tree commit diff
path: root/views
diff options
context:
space:
mode:
authorFlorian Klink <flokli@flokli.de>2023-03-03T14·17+0100
committerflokli <flokli@flokli.de>2023-03-03T14·56+0000
commitdfb8b7a2661d00a92e7732139560637e9a26867e (patch)
tree41c42015cc9a8ac360452aa588e2fbc86c7d83ca /views
parent48a80dfea0466e75fed77e5b27e7f7668e371dd0 (diff)
docs(views): extend README for josh-filter usage r/5874
Also document how these can be cloned by referring to a custom Gerrit
ref.

Change-Id: I5495a1c29bdd6d78215af7307953437f9cbca5db
Reviewed-on: https://cl.tvl.fyi/c/depot/+/8198
Tested-by: BuildkiteCI
Reviewed-by: tazjin <tazjin@tvl.su>
Diffstat (limited to 'views')
-rw-r--r--views/README.md27
1 files changed, 26 insertions, 1 deletions
diff --git a/views/README.md b/views/README.md
index 83464d5ee21d..183e70bc5a5d 100644
--- a/views/README.md
+++ b/views/README.md
@@ -3,4 +3,29 @@ depot views
 
 This folder contains external views of depot content, defined using
 josh workspaces. See the individual views for a description of their
-content and usage information.
+individual content and usage information.
+
+Testing changes locally
+-----------------------
+
+Generally, when iterating on these files, it's best to locally invoke `josh-
+filter` (from `//third_party//josh`) locally to inspect how the workspace would
+look like:
+
+  - Commit your changes. This is required, as `josh-filter` operates on your
+    `HEAD`, not working directory state.
+  - Invoke `josh-filter` with the filter expression,
+    for example `josh-filter ':workspace=views/kit'`.
+  - Peek at the synthesized git history by looking at `FILTERED_HEAD`.
+
+Testing changes in Gerrit
+-------------------------
+
+It's also possible to clone resulting workspaces for CLs that were already
+pushed to Gerrit, but didn't land in master yet.
+
+For CL1234 at revision 2, the URL passed to `git clone` would look like this:
+
+```
+https://code.tvl.fyi/depot.git@refs/changes/32/1234/2:workspace=views/kit.git
+````