Brim wiki updates for v0.25.0 release #1723
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Apologies in advance for the size of this PR. Due to the need to hyperlink between articles, this would have been difficult to do in small pieces. To do my own proofreading, I've cloned a copy of the docs in this branch to a separate repo that similarly publishes to a GitHub wiki. Therefore my suggestion to reviewers might be to just read that over at https:/philrz/scratchwiki/wiki with fresh eyes rather than try to make sense of every diff.
The approach I'm taking with this PR is to show up-to-date info about the new Brim without completely replacing all of the old content. This is due to the fact that Windows and Linux users will not be auto-updated the new release, and in the event users report big bugs right after we release
v0.25.0
, we might not even push users to upgrade super fast. So there may be a period when users will want to self-service with docs about their older release and/or I might need to send such links to help users. It would have been nice if we could maintain a single article on each topic and have the parts specific to old/new versions at the relevant spots, but due to the largeness of some changes (the Brimcap unbundling, the role of the Zed Lake, etc.) this became unwieldy for some articles. For those couple bigger topics, I ended up keeping the older content under its existing filename in hopes of not breaking too many bookmarks/hyperlinks in the interim, but added a blurb up top noting the relevant version and linking to the parallel doc that covers the newer. Meanwhile each one covering the newer Brim is at a new filename for now. After we've had a couple follow-on releases beyondv0.25.0
and it seems like most/all users have transitioned, I can move the newer content to the original filenames and phase out the old content entirely.Since this was an opportunity to reassess and re-test a bunch of the docs, I changed a few other things along the way.
I noticed I've had to keep adding tables to articles showing paths on the filesystem where the app binaries and/or user data are stored, and that was about to get worse because the app binaries have different paths with the new installer. Therefore I've created a separate article just about the filesystem paths, which also provided a nice opportunity to explain the read-only/read-write nature of each. I think it also made the other articles a little cleaner.
The Geolocation article started to look out of place after the other stuff had been overhauled, so I ended up moving it to the Brimcap wiki. See Geolocation article (moved from Brim wiki) brimcap#104 for details.
With 20/20 hindsight, I can see how the Join article I wrote for
v0.24.0
is not great (too much leading text, too Zeek-specific, etc.) so I didn't want to invest time in trying to make an updated version of that content. Instead I've added the placeholder blurb at the top of the old article, and once In-line inputs for automated checking of docs examples zed#2627 gets merged I intend to write properjoin
coverage where it belongs in the Zed operators doc. After that, I think I will create a parallel Join article that shows thev0.25.0
approach of usingzapi
outside the app and pushing joined data back in, and it'll link to that operator doc.Closes #1694