Yehowshua/ZIm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

WIP

Browse source
This commit is contained in:
Nate Butler 2023-12-11 19:17:13 -05:00
parent fcbc18a380
commit 9cb6f6689e
24 changed files with 1778 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
book
.vercel

52
docs/backend-development.md
View file

@ -1,52 +0,0 @@
[⬅ Back to Index](./index.md)
# Developing Zed's Backend
Zed's backend consists of the following components:
- The Zed.dev web site
- implemented in the [`zed.dev`](https://github.com/zed-industries/zed.dev) repository
- hosted on [Vercel](https://vercel.com/zed-industries/zed-dev).
- The Zed Collaboration server
- implemented in the [`crates/collab`](https://github.com/zed-industries/zed/tree/main/crates/collab) directory of the main `zed` repository
- hosted on [DigitalOcean](https://cloud.digitalocean.com/projects/6c680a82-9d3b-4f1a-91e5-63a6ca4a8611), using Kubernetes
- The Zed Postgres database
- defined via migrations in the [`crates/collab/migrations`](https://github.com/zed-industries/zed/tree/main/crates/collab/migrations) directory
- hosted on DigitalOcean
---
## Local Development
Here's some things you need to develop backend code locally.
### Dependencies
- **Postgres** - download [Postgres.app](https://postgresapp.com).
### Setup
1. Check out the `zed` and `zed.dev` repositories into a common parent directory
2. Set the `GITHUB_TOKEN` environment variable to one of your GitHub personal access tokens (PATs).
- You can create a PAT [here](https://github.com/settings/tokens).
- You may want to add something like this to your `~/.zshrc`:
```
export GITHUB_TOKEN=<the personal access token>
```
3. In the `zed.dev` directory, run `npm install` to install dependencies.
4. In the `zed directory`, run `script/bootstrap` to set up the database
5. In the `zed directory`, run `foreman start` to start both servers
---
## Production Debugging
### Datadog
Zed uses Datadog to collect metrics and logs from backend services. The Zed organization lives within Datadog's _US5_ [site](https://docs.datadoghq.com/getting_started/site/), so it can be accessed at [us5.datadoghq.com](https://us5.datadoghq.com). Useful things to look at in Datadog:
- The [Logs](https://us5.datadoghq.com/logs) page shows logs from Zed.dev and the Collab server, and the internals of Zed's Kubernetes cluster.
- The [collab metrics dashboard](https://us5.datadoghq.com/dashboard/y2d-gxz-h4h/collab?from_ts=1660517946462&to_ts=1660604346462&live=true) shows metrics about the running collab server

6
docs/book.toml Normal file
View file

@ -0,0 +1,6 @@
[book]
authors = ["Nate Butler"]
language = "en"
multilingual = false
src = "src"
title = "Zed App Docs"

34
docs/company-and-vision.md
View file

@ -1,34 +0,0 @@
[⬅ Back to Index](./index.md)
# Company & Vision
## Vision
Our goal is to make Zed the primary tool software teams use to collaborate.
To do this, Zed will...
* Make collaboration a first-class feature of the code authoring environment.
* Enable text-based conversations about any piece of text, independent of whether/when it was committed to version control.
* Make it smooth to edit and discuss code with teammates in real time.
* Make it easy to recall past conversations any area of the code.
We believe the best way to make collaboration amazing is to build it into a new editor rather than retrofitting an existing editor. This means that in order for a team to adopt Zed for collaboration, each team member will need to adopt it as their editor as well.
For this reason, we need to deliver a clearly superior experience as a single-user code editor in addition to being an excellent collaboration tool. This will take time, but we believe the dominance of VS Code demonstrates that it's possible for a single tool to capture substantial market share. We can proceed incrementally, capturing one team at a time and gradually transitioning conversations away from GitHub.
## Zed Values
Everyone wants to work quickly and have a lot of users. What are we unwilling to sacrifice in pursuit of those goals?
- **Performance.** Speed is core to our brand and value proposition. It's important that we consistently deliver a response in less than 8ms on modern hardware for fine-grained actions. Coarse-grained actions should render feedback within 50ms. We consider the performance goals of the product at all times, and take the time to ensure our code meets them with reasonable usage. Once we have met our goals, we assess the impact vs effort of further performance investment and know when to say when. We measure our performance in the field and make an effort to maintain or improve real-world performance and promptly address regressions.
- **Craftsmanship.** Zed is a premium product, and we put care into design and user experience. We can always cut scope, but what we do ship should be quality. Incomplete is okay, so long as we're executing on a coherent subset well. Half-baked, unintuitive, or broken is not okay.
- **Shipping.** Knowledge matters only in as much as it drives results. We're here to build a real product in the real world. We care a lot about the experience of developing Zed, but we care about the user's experience more.
- **Code quality.** This enables craftsmanship. Nobody is creative in a trash heap, and we're willing to dedicate time to keep our codebase clean. If we're spending no time refactoring, we are likely underinvesting. When we realize a design flaw, we assess its centrality to the rest of the system and consider budgeting time to address it. If we're spending all of our time refactoring, we are likely either overinvesting or paying off debt from past underinvestment. It's up to each engineer to allocate a reasonable refactoring budget. We shouldn't be navel gazing, but we also shouldn't be afraid to invest.
- **Pairing.** Zed depends on regular pair programming to promote cohesion on our remote team. We believe pairing is a powerful substitute for beuracratic management, excessive documentation, and tedious code review. Nobody has to pair all day, every day, but everyone is responsible for pairing at least 2 hours a week with a variety of other engineers. If anyone wants to pair all day every day, that is explicitly endorsed and credited. If pairing temporarily reduces our throughput due to working on one thing instead of two, we trust that it will pay for itself in the long term by increasing our velocity and allowing us to more effectively grow our team.
- **Long-term thinking.** The Zed vision began several years ago, and we expect Zed to be around many years from today. We must always be mindful to avoid overengineering for the future, but we should also keep the long-term in mind. Are we building a system our future selves would want to work on in 5 years?

74
docs/design-tools.md
View file

@ -1,74 +0,0 @@
[⬅ Back to Index](./index.md)
# Design Tools & Links
Generally useful tools and resources for design.
## General
[Names of Signs & Symbols](https://www.prepressure.com/fonts/basics/character-names#curlybrackets)
[The Noun Project](https://thenounproject.com/) - Icons for everything, attempts to describe all of human language visually.
[SVG Repo](https://www.svgrepo.com/) - Open-licensed SVG Vector and Icons
[Font Awsesome](https://fontawesome.com/) - High quality icons, has been around for many years.
---
## Color
[Opacity/Transparency Hex Values](https://gist.github.com/lopspower/03fb1cc0ac9f32ef38f4)
[Color Ramp Generator](https://lyft-colorbox.herokuapp.com)
[Designing a Comprehensive Color System
](https://www.rethinkhq.com/videos/designing-a-comprehensive-color-system-for-lyft) - [Linda Dong](https://twitter.com/lindadong)
---
## Figma & Plugins
[Figma Plugins for Designers](https://www.uiprep.com/blog/21-best-figma-plugins-for-designers-in-2021)
[Icon Resizer](https://www.figma.com/community/plugin/739117729229117975/Icon-Resizer)
[Code Syntax Highlighter](https://www.figma.com/community/plugin/938793197191698232/Code-Syntax-Highlighter)
[Proportional Scale](https://www.figma.com/community/plugin/756895186298946525/Proportional-Scale)
[LilGrid](https://www.figma.com/community/plugin/795397421598343178/LilGrid)
Organize your selection into a grid.
[Automator](https://www.figma.com/community/plugin/1005114571859948695/Automator)
Build photoshop-style batch actions to automate things.
[Figma Tokens](https://www.figma.com/community/plugin/843461159747178978/Figma-Tokens)
Use tokens in Figma and generate JSON from them.
---
## Design Systems
### Naming
[Naming Design Tokens](https://uxdesign.cc/naming-design-tokens-9454818ed7cb)
### Storybook
[Collaboration with design tokens and storybook](https://zure.com/blog/collaboration-with-design-tokens-and-storybook/)
### Example DS Documentation
[Tailwind CSS Documentation](https://tailwindcss.com/docs/container)
[Material Design Docs](https://material.io/design/color/the-color-system.html#color-usage-and-palettes)
[Carbon Design System Docs](https://www.carbondesignsystem.com)
[Adobe Spectrum](https://spectrum.adobe.com/)
- Great documentation, like [Color System](https://spectrum.adobe.com/page/color-system/) and [Design Tokens](https://spectrum.adobe.com/page/design-tokens/).
- A good place to start if thinking about building a design system.

14
docs/index.md
View file

@ -1,14 +0,0 @@
[⬅ Back to Index](./index.md)
# Welcome to Zed
Welcome! These internal docs are a work in progress. You can contribute to them by submitting a PR directly!
## Contents
- [The Company](./company-and-vision.md)
- [Tools We Use](./tools.md)
- [Building Zed](./building-zed.md)
- [Release Process](./release-process.md)
- [Backend Development](./backend-development.md)
- [Design Tools & Links](./design-tools.md)

96
docs/release-process.md
View file

@ -1,96 +0,0 @@
[⬅ Back to Index](./index.md)
# Zed's Release Process
The process to create and ship a Zed release
## Overview
### Release Channels
Users of Zed can choose between two _release channels_ - 'Stable' and 'Preview'. Most people use Stable, but Preview exists so that the Zed team and other early-adopters can test new features before they are released to our general user-base.
### Weekly (Minor) Releases
We normally publish new releases of Zed on Wednesdays, for both the Stable and Preview channels. For each of these releases, we bump Zed's _minor_ version number.
For the Preview channel, we build the new release based on what's on the `main` branch. For the Stable channel, we build the new release based on the last Preview release.
### Hotfix (Patch) Releases
When we find a _regression_ in Zed (a bug that wasn't present in an earlier version), or find a significant bug in a newly-released feature, we typically publish a hotfix release. For these releases, we bump Zed's _patch_ version number.
### Server Deployments
Often, changes in the Zed app require corresponding changes in the `collab` server. At the currente stage of our copmany, we don't attempt to keep our server backwards-compatible with older versions of the app. Instead, when making a change, we simply bump Zed's _protocol version_ number (in the `rpc` crate), which causes the server to recognize that it isn't compatible with earlier versions of the Zed app.
This means that when releasing a new version of Zed that has changes to the RPC protocol, we need to deploy a new version of the `collab` server at the same time.
## Instructions
### Publishing a Minor Release
1. Announce your intent to publish a new version in Discord. This gives other people a chance to raise concerns or postpone the release if they want to get something merged before publishing a new version.
1. Open your terminal and `cd` into your local copy of Zed. Checkout `main` and perform a `git pull` to ensure you have the latest version.
1. Run the following command, which will update two git branches and two git tags (one for each release channel):
```
script/bump-zed-minor-versions
```
1. The script will make local changes only, and print out a shell command that you can use to push all of these branches and tags.
1. Pushing the two new tags will trigger two CI builds that, when finished, will create two draft releases (Stable and Preview) containing `Zed.dmg` files.
1. Now you need to write the release notes for the Stable and Preview releases. For the Stable release, you can just copy the release notes from the last week's Preview release, plus any hotfixes that were published on the Preview channel since then. Some of the hotfixes may not be relevant for the Stable release notes, if they were fixing bugs that were only present in Preview.
1. For the Preview release, you can retrieve the list of changes by running this command (make sure you have at least `Node 18` installed):
```
GITHUB_ACCESS_TOKEN=your_access_token script/get-preview-channel-changes
```
1. The script will list all the merged pull requests and you can use it as a reference to write the release notes. If there were protocol changes, it will also emit a warning.
1. Once CI creates the draft releases, add each release's notes and save the drafts.
1. If there have been server-side changes since the last release, you'll need to re-deploy the `collab` server. See below.
1. Before publishing, download the Zed.dmg and smoke test it to ensure everything looks good.
### Publishing a Patch Release
1. Announce your intent to publish a new patch version in Discord.
1. Open your terminal and `cd` into your local copy of Zed. Check out the branch corresponding to the release channel where the fix is needed. For example, if the fix is for a bug in Stable, and the current stable version is `0.63.0`, then checkout the branch `v0.63.x`. Run `git pull` to ensure your branch is up-to-date.
1. Find the merge commit where your bug-fix landed on `main`. You can browse the merged pull requests on main by running `git log main --grep Merge`.
1. Cherry-pick those commits onto the current release branch:
```
git cherry-pick -m1 <THE-COMMIT-SHA>
```
1. Run the following command, which will bump the version of Zed and create a new tag:
```
script/bump-zed-patch-version
```
1. The script will make local changes only, and print out a shell command that you can use to push all the branch and tag.
1. Pushing the new tag will trigger a CI build that, when finished, will create a draft release containing a `Zed.dmg` file.
1. Once the draft release is created, fill in the release notes based on the bugfixes that you cherry-picked.
1. If any of the bug-fixes require server-side changes, you'll need to re-deploy the `collab` server. See below.
1. Before publishing, download the Zed.dmg and smoke test it to ensure everything looks good.
1. Clicking publish on the release will cause old Zed instances to auto-update and the Zed.dev releases page to re-build and display the new release.
### Deploying the Server
1. Deploying the server is a two-step process that begins with pushing a tag. 1. Check out the commit you'd like to deploy. Often it will be the head of `main`, but could be on any branch.
1. Run the following script, which will bump the version of the `collab` crate and create a new tag. The script takes an argument `minor` or `patch`, to indicate how to increment the version. If you're releasing new features, use `minor`. If it's just a bugfix, use `patch`
```
script/bump-collab-version patch
```
1. This script will make local changes only, and print out a shell command that you can use to push the branch and tag.
1. Pushing the new tag will trigger a CI build that, when finished will upload a new versioned docker image to the DigitalOcean docker registry.
1. Once that CI job completes, you will be able to run the following command to deploy that docker image. The script takes two arguments: an environment (`production`, `preview`, or `staging`), and a version number (e.g. `0.10.1`).
```
script/deploy preview 0.10.1
```
1. This command should complete quickly, updating the given environment to use the given version number of the `collab` server.

128
docs/src/CODE_OF_CONDUCT.md Normal file
View file

@ -0,0 +1,128 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or
advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
hi@zed.dev.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series
of actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
the community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).
[homepage]: https://www.contributor-covenant.org
For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.

3
docs/src/CONTRIBUTING.md Normal file
View file

@ -0,0 +1,3 @@
# Contributing
TBD

18
docs/src/SUMMARY.md Normal file
View file

@ -0,0 +1,18 @@
# Summary
[Getting Started](./getting_started.md)
[Feedback](./feedback.md)
# Configuring Zed
- [Settings](./configuring_zed.md)
- [Vim Mode](./configuring_zed__configuring_vim.md)
# Developing Zed
- [Building from Source](./developing_zed__building_zed.md)
- [Local Collaboration](./developing_zed__local_collaboration.md)
- [Adding Languages](./developing_zed__adding_languages.md)
# Other
- [Code of Conduct](./CODE_OF_CONDUCT.md)
- [Telemetry](./telemetry.md)
- [Contributing](./CONTRIBUTING.md)

1035
docs/src/configuring_zed.md Normal file
View file

File diff suppressed because it is too large Load diff

170
docs/src/configuring_zed__configuring_vim.md Normal file
View file

@ -0,0 +1,170 @@
# Vim Mode
Zed includes a vim emulation layer known as “vim mode”. This document aims to describe how it works, and how to make the most out of it.
### Philosophy
Vim mode in Zed is supposed to primarily "do what you expect": it mostly tries to copy vim exactly, but will use Zed-specific functionality when available to make things smoother.
This means Zed will never be 100% vim compatible, but should be 100% vim familiar! We expect that our vim mode already copes with 90% of your workflow, and we'd like to keep improving it. If you find things that you can’t yet do in vim mode, but which you rely on in your current workflow, please leave feedback in the editor itself (`:feedback`), or [file an issue](https://github.com/zed-industries/community).
### Zed-specific features
Zed is built on a modern foundation that (among other things) uses tree-sitter to understand the content of the file you're editing, and supports multiple cursors out of the box.
Vim mode has several "core Zed" key bindings, that will help you make the most of Zed's specific feature set.
```
# Normal mode
g d Go to definition
g D Go to type definition
c d Rename (change definition)
g A Go to All references to the current word
g <space> Open the current search excerpt in its own tab
g s Find symbol in current file
g S Find symbol in entire project
g n Add a visual selection for the next copy of the current word
g N The same, but backwards
g > Skip latest word selection, and add next.
g < The same, but backwards
g a Add a visual selection for every copy of the current word
g h Show inline error (hover)
# Insert mode
ctrl-x ctrl-o Open the completion menu
ctrl-x ctrl-c Request Github Copilot suggestion (if configured)
ctrl-x ctrl-a Open the inline AI assistant (if configured)
ctrl-x ctrl-l Open the LSP code actions
ctrl-x ctrl-z Hides all suggestions
```
Vim mode uses Zed to define concepts like "brackets" (for the `%` key) and "words" (for motions like `w` and `e`). This does lead to some differences, but they are mostly positive. For example `%` considers `|` to be a bracket in languages like Rust; and `w` considers `$` to be a word-character in languages like Javascript.
Vim mode emulates visual block mode using Zed's multiple cursor support. This again leads to some differences, but is much more powerful.
Finally, Vim mode's search and replace functionality is backed by Zed's. This means that the pattern syntax is slightly different, see the section on [Regex differences](#regex-differences) for details.
### Custom key bindings
Zed does not yet have an equivalent to vim’s `map` command to convert one set of keystrokes into another, however you can bind any sequence of keys to fire any Action documented in the [Key bindings documentation](https://docs.zed.dev/configuration/key-bindings).
You can edit your personal key bindings with `:keymap`.
For vim-specific shortcuts, you may find the following template a good place to start:
```json
[
{
"context": "Editor && VimControl && !VimWaiting && !menu",
"bindings": {
// put key-bindings here if you want them to work in normal & visual mode
}
},
{
"context": "Editor && vim_mode == normal && !VimWaiting && !menu",
"bindings": {
// put key-bindings here if you want them to work only in normal mode
}
},
{
"context": "Editor && vim_mode == visual && !VimWaiting && !menu",
"bindings": {
// visual, visual line & visual block modes
}
},
{
"context": "Editor && vim_mode == insert && !menu",
"bindings": {
// put key-bindings here if you want them to work in insert mode
}
}
]
```
You can see the bindings that are enabled by default in vim mode [here](https://zed.dev/ref/vim.json).
The details of the context are a little out of scope for this doc, but suffice to say that `menu` is true when a menu is open (e.g. the completions menu), `VimWaiting` is true after you type `f` or `t` when we’re waiting for a new key (and you probably don’t want bindings to happen). Please reach out on [Github](https://github.com/zed-industries/community) if you want help making a key bindings work.
### Command palette
Vim mode allows you to enable Zed’s command palette with `:`. This means that you can use vim's command palette to run any action that Zed supports.
Additionally vim mode contains a number of aliases for popular vim commands to ensure that muscle memory works. For example `:w<enter>` will save the file.
We do not (yet) emulate the full power of vim’s command line, in particular we special case specific patterns instead of using vim's range selection syntax, and we do not support arguments to commands yet. Please reach out on [Github](https://github.com/zed-industries/community) as you find things that are missing from the command palette.
As mentioned above, one thing to be aware of is that the regex engine is slightly different from vim's in `:%s/a/b`.
Currently supported vim-specific commands (as of Zed 0.106):
```
# window management
:w[rite][!], :wq[!], :q[uit][!], :wa[ll][!], :wqa[ll][!], :qa[ll][!], :[e]x[it][!], :up[date]
to save/close tab(s) and pane(s) (no filename is supported yet)
:cq
to quit completely.
:vs[plit], :sp[lit]
to split vertically/horizontally (no filename is supported yet)
:new, :vne[w]
to create a new file in a new pane above or to the left
:tabedit, :tabnew
to create a new file in a new tab.
:tabn[ext], :tabp[rev]
to go to previous/next tabs
:tabc[lose]
to close the current tab
# navigating diagnostics
:cn[ext], :cp[rev], :ln[ext], :lp[rev]
to go to the next/prev diagnostics
:cc, :ll
to open the errors page
# jump to position
:<number>
to jump to a line number
:$
to jump to the end of the file
:/foo and :?foo
to jump to next/prev line matching foo
# replacement
:%s/foo/bar/
to replace instances of foo with bar (/g is always assumed, the range must always be %, and Zed uses different regex syntax to vim)
# editing
:j[oin]
to join the current line (no range is yet supported)
:d[elete][l][p]
to delete the current line (no range is yet supported)
:s[ort] [i]
to sort the current selection (with i, case-insensitively)
```
### Related settings
There are a few Zed settings that you may also enjoy if you use vim mode:
```
{
// disable cursor blink
"cursor_blink": false
// use relative line numbers
"relative_line_numbers": true,
// hide the scroll bar
"scrollbar": {"show": "never"},
}
```
### Regex differences
Zed uses a different regular expression engine from Vim. This means that you will have to use a different syntax for some things.
Notably:
* Vim uses `\(` and `\)` to represent capture groups, in Zed these are `(` and `)`.
* On the flip side, `(` and `)` represent literal parentheses, but in Zed these must be escaped to `\(` and `\)`.
* When replacing, Vim uses `\0` to represent the entire match, in Zed this is `$0`, same for numbered capture groups `\1` -> `$1`.
* Vim uses `\<` and `\>` to represent word boundaries, in Zed these are both handled by `\b`
* Vim uses `/g` to indicate "all matches on one line", in Zed this is implied
* Vim uses `/i` to indicate "case-insensitive", in Zed you can either use `(?i)` at the start of the pattern or toggle case-sensitivity with `cmd-option-c`.
To help with the transition, the command palette will fix parentheses and replace groups for you when you run `:%s//`. So `%s:/\(a\)(b)/\1/` will be converted into a search for "(a)\(b\)" and a replacement of "$1".
For the full syntax supported by Zed's regex engine see the [regex crate documentation](https://docs.rs/regex/latest/regex/#syntax).

16
docs/zed/syntax-highlighting.md → docs/src/developing_zed__adding_languages.md
View file

@ -1,12 +1,16 @@
# Syntax Highlighting in Zed
# Adding New Languages to Zed
This doc is a work in progress!
## LSP
## Defining syntax highlighting rules
Zed uses the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) to provide language support. This means, in theory, we can support any language that has an LSP server.
## Syntax Highlighting
### Defining syntax highlighting rules
We use tree-sitter queries to match certian properties to highlight.
### Simple Example:
#### Simple Example:
```scheme
(property_identifier) @property
@ -22,7 +26,7 @@ const font: FontFamily = {
Match a property identifier and highlight it using the identifier `@property`. In the above example, `weight`, `underline`, and `italic` would be highlighted.
### Complex example:
#### Complex example:
```scheme
(_
@ -42,7 +46,7 @@ function buildDefaultSyntax(colorScheme: Theme): Partial<Syntax> {
Match a function return type, and highlight the type using the identifier `@type.return`. In the above example, `Partial` would be highlighted.
### Example - Typescript
#### Example - Typescript
Here is an example portion of our `highlights.scm` for TypeScript:

7
docs/building-zed.md → docs/src/developing_zed__building_zed.md
View file

@ -1,7 +1,10 @@
[⬅ Back to Index](./index.md)
# Building Zed
🚧 TODO:
- [ ] Tidy up & update instructions
- [ ] Remove ZI-specific things
- [ ] Rework any steps that currently require a ZI-specific account
How to build Zed from source for the first time.
## Prerequisites

0
docs/local-collaboration.md → docs/src/developing_zed__local_collaboration.md
View file

29
docs/src/feedback.md Normal file
View file

@ -0,0 +1,29 @@
# Giving feedback
### Community repository
We track our issues at [`zed-industries/community`](https://github.com/zed-industries/community/issues).
#### Feature requests
Try to focus on the things that are most critical to you rather than exhaustively listing all features another editor you have used has.
Command palette: `request feature`
#### Bug reports
Try to add as much detail as possible, if it is not obvious to reproduce. Let us know how severe the problem is for you; is the issue more of a minor inconvenience or something that would prevent you from using Zed?
Command palette: `file bug report`
### In-app feedback
Anonymous feedback can be submitted from within Zed via the feedback editor (command palette: `give feedback`).
### Zed forum
Use the [community forum](https://github.com/zed-industries/community/discussions) to ask questions and learn from one another. We will be present in the forum and answering questions as well.
### Email
If you prefer to write up your thoughts as an email, you can send them to [hi@zed.dev](mailto:hi@zed.dev).

15
docs/src/getting_started.md Normal file
View file

@ -0,0 +1,15 @@
# Getting Started
Welcome to Zed! We are excited to have you. Here is a jumping-off point to getting started.
### Download Zed
You can obtain the release build via the [download page](https://zed.dev/download). After the first manual installation, Zed will periodically check for and install updates automatically for you.
### Configure Zed
Use `CMD + ,` to open your custom settings to set things like fonts, formatting settings, per-language settings and more. You can access the default configuration using the `Zed > Settings > Open Default Settings` menu item. See Configuring Zed for all available settings.
### Set up your key bindings
You can access the default key binding set using the `Zed > Settings > Open Default Key Bindings` menu item. Use `CMD + K`,`CMD + S` to open your custom keymap to add your own key bindings. See Key Bindings for more info.,

13
docs/src/system_requirements.md Normal file
View file

@ -0,0 +1,13 @@
# System Requirements
## macOS
Supported versions: Catalina (10.15) - Ventura (13.x).
{% hint style="info" %}
The implementation of our screen sharing feature makes use of [LiveKit](https://livekit.io). The LiveKit SDK requires macOS Catalina (10.15); consequently, in v0.62.4, we dropped support for earlier macOS versions that we were initially supporting.
{% endhint %}
## Linux, Windows, and Web
_Not supported at this time. See our_ [_Platform Support_](https://github.com/zed-industries/community/issues/174) _issue._

147
docs/src/telemetry.md Normal file
View file

@ -0,0 +1,147 @@
# Telemetry in Zed
**Up to date with v0.112.0**
Zed collects anonymous telemetry data to help the team understand how people are using the application and to see what sort of issues they are experiencing.
## Dataflow
Telemetry is sent from the application to zed.dev. Data is proxied through our servers to enable us to easily switch analytics services; we never store this data. The data is then sent off to various services:
- [Datadog](https://www.datadoghq.com): Cloud-monitoring service - stores diagnostic events
- [Clickhouse](https://clickhouse.com): Business Intelligence platform - stores both diagnostic and metric events
- [Metabase](https://www.metabase.com): Dashboards - dashboards built around data pulled from Clickhouse
## Types of Telemetry
### Diagnostics
Diagnostic events include debug information (stack traces) from crash reports. Reports are sent on the first application launch after the crash occurred. We've built dashboards that allow us to visualize the frequency and severity of issues experienced by users. Having these reports sent automatically allows us to begin implementing fixes without the user needing to file a report in our issue tracker. The plots in the dashboards also give us an informal measurement of the stability of Zed.
When a panic occurs, the following data is sent:
#### PanicRequest
- `panic`: The panic data
- `token`: An identifier that is used to authenticate the request on zed.dev
#### Panic
- `thread`: The name of the thread that panicked
- `payload`: The panic message
- `location_data`: The location of the panic
- `file`
- `line`
- `backtrace`: The backtrace of the panic
- `app_version`: Zed's app version
- `release_channel`: Zed's release channel
- `stable`
- `preview`
- `dev`
- `os_name`: The name of your operating system
- `os_version`: The version of your operating system
- `architecture`: The architecture of your CPU
- `panicked_on`: The time that the panic occurred
- `installation_id`: An identifier that is unique to each installation of Zed (this differs for stable, preview, and dev builds)
- `session_id`: An identifier that is unique to each Zed session (this differs for each time you open Zed)
### Metrics
Zed also collects metric information based on user actions. Metric events are reported over HTTPS, and requests are rate-limited to avoid using significant network bandwidth. All data remains anonymous, and can't be related to specific Zed users.
The following data is sent:
#### ClickhouseEventRequestBody
- `token`: An identifier that is used to authenticate the request on zed.dev
- `installation_id`: An identifier that is unique to each installation of Zed (this differs for stable, preview, and dev builds)
- `session_id`: An identifier that is unique to each Zed session (this differs for each time you open Zed)
- `is_staff`: A boolean that indicates whether the user is a member of the Zed team or not
- `app_version`: Zed's app version
- `os_name`: The name of your operating system
- `os_version`: The version of your operating system
- `architecture`: The architecture of your CPU
- `release_channel`: Zed's release channel
- `stable`
- `preview`
- `dev`
- `events`: A vector of `ClickhouseEventWrapper`s
#### ClickhouseEventWrapper
- `signed_in`: A boolean that indicates whether the user is signed in or not
- `event`: An enum, where each variant can be one of the following `ClickhouseEvent` variants:
#### ClickhouseEvent
- `editor`
- `operation`: The editor operation that was performed
- `open`
- `save`
- `file_extension`: The extension of the file that was opened or saved
- `vim_mode`: A boolean that indicates whether the user is in vim mode or not
- `copilot_enabled`: A boolean that indicates whether the user has copilot enabled or not
- `copilot_enabled_for_language`: A boolean that indicates whether the user has copilot enabled for the language of the file that was opened or saved
- `milliseconds_since_first_event`: Duration of time between this event's timestamp and the timestamp of the first event in the current batch
- `copilot`
- `suggestion_id`: The ID of the suggestion
- `suggestion_accepted`: A boolean that indicates whether the suggestion was accepted or not
- `file_extension`: The file extension of the file that was opened or saved
- `milliseconds_since_first_event`: Same as above
- `call`
- `operation`: The call operation that was performed
- `accept incoming`
- `decline incoming`
- `disable microphone`
- `disable screen share`
- `enable microphone`
- `enable screen share`
- `hang up`
- `invite`
- `join channel`
- `open channel notes`
- `share project`
- `unshare project`
- `room_id`: The ID of the room
- `channel_id`: The ID of the channel
- `milliseconds_since_first_event`: Same as above
- `assistant`
- `conversation_id`: The ID of the conversation (for panel events only)
- `kind`: An enum with the following variants:
- `panel`
- `inline`
- `model`: The model that was used
- `milliseconds_since_first_event`: Same as above
- `cpu`
- `usage_as_percentage`: The CPU usage
- `core_count`: The number of cores on the CPU
- `milliseconds_since_first_event`: Same as above
- `memory`
- `memory_in_bytes`: The amount of memory used in bytes
- `virtual_memory_in_bytes`: The amount of virtual memory used in bytes
- `milliseconds_since_first_event`: Same as above
- `app`
- `operation`: The app operation that was performed
- `first open`
- `open`
- `close (only in GPUI2-powered Zed)`
- `milliseconds_since_first_event`: Same as above
You can audit the metrics data that Zed has reported by running the command `zed: open telemetry log` from the command palette, or clicking `Help > View Telemetry Log` in the application menu.
### Configuring Telemetry Settings
You have full control over what data is sent out by Zed. To enable or disable some or all telemetry types, open your `settings.json` file via `zed: open settings` from the command palette. Insert and tweak the following:
```json
"telemetry": {
"diagnostics": false,
"metrics": false
},
```
The telemetry settings can also be configured via the `welcome` screen, which can be invoked via the `workspace: welcome` action in the command palette.
### Concerns and Questions
If you have concerns about telemetry, please feel free to open issues in our [community repository](https://github.com/zed-industries/community/issues/new/choose).

29
docs/theme/generating-theme-types.md vendored
View file

@ -1,29 +0,0 @@
[⬅ Back to Index](../index.md)
# Generating Theme Types
## How to generate theme types:
Run a script
```bash
./script/build-theme-types
```
Types are generated in `styles/src/types/zed.ts`
## How it works:
1. Rust types
The `crates/theme` contains theme types.
Crate `schemars` used to generate a JSON schema from the theme structs.
Every struct that represent theme type has a `#[derive(JsonSchema)]` attribute.
Task lotaked at `crates/xtask/src/main.rs` generates a JSON schema from the theme structs.
2. TypeScript types
Script `npm run build-types` from `styles` package generates TypeScript types from the JSON schema and saves them to `styles/src/types/zed.ts`.

82
docs/tools.md
View file

@ -1,82 +0,0 @@
[⬅ Back to Index](./index.md)
# Tools
Tools to get started at Zed. Work in progress, submit a PR to add any missing tools here!
---
## Everyday Tools
### Calendar
To gain access to company calendar, visit [this link](https://calendar.google.com/calendar/u/0/r?cid=Y18xOGdzcGE1aG5wdHJocGRoNWtlb2tlbWxzc0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t).
If you would like the company calendar to be synced with a calendar application (Apple Calendar, etc.):
- Add your company account (i.e `joseph@zed.dev`) to your calendar application
- Visit [this link](https://calendar.google.com/calendar/u/0/syncselect), check `Zed Industries (Read Only)` under `Shared Calendars`, and save it.
### 1Password
We have a shared company 1Password with all of our credentials. To gain access:
1. Go to [zed-industries.1password.com](https://zed-industries.1password.com).
1. Sign in with your `@zed.dev` email address.
1. Make your account and let an admin know you've signed up.
1. Once they approve your sign up, you'll have access to all of the company credentials.
### Slack
Have a team member add you to the [Zed Industries](https://zed-industries.slack.com/) slack.
### Discord
We have a Discord community. You can use [this link](https://discord.gg/SSD9eJrn6s) to join. **!Don't share this link, this is specifically for team members!**
Once you have joined the community, let a team member know and we can add your correct role.
---
## Engineering
### Github
For now, all the Zed source code lives on [Github](https://github.com/zed-industries). A founder will need to add you to the team and set up the appropriate permissions.
Useful repos:
- [zed-industries/zed](https://github.com/zed-industries/zed) - Zed source
- [zed-industries/zed.dev](https://github.com/zed-industries/zed.dev) - Zed.dev site and collab API
- [zed-industries/docs](https://github.com/zed-industries/docs) - Zed public docs
- [zed-industries/community](https://github.com/zed-industries/community) - Zed community feedback & discussion
### Vercel
We use Vercel for all of our web deployments and some backend things. If you sign up with your `@zed.dev` email you should be invited to join the team automatically. If not, ask a founder to invite you to the Vercel team.
### Environment Variables
You can get access to many of our shared enviroment variables through 1Password and Vercel. For 1Password search the value you are looking for, or sort by passwords or API credentials.
For Vercel, go to `settings` -> `Environment Variables` (either on the entire org, or on a specific project depending on where it is shared.) For a given Vercel project if you have their CLI installed you can use `vercel pull` or `vercel env` to pull values down directly. More on those in their [CLI docs](https://vercel.com/docs/cli/env).
---
## Design
### Figma
We use Figma for all of our design work. To gain access:
1. Use [this link](https://www.figma.com/team_invite/redeem/Xg4RcNXHhwP5netIvVBmKQ) to join the Figma team.
1. You should now have access to all of the company files.
1. You should go to the team page and "favorite" (star) any relevant projects so they show up in your sidebar.
1. Download the [Figma app](https://www.figma.com/downloads/) for easier access on desktop.
### Campsite
We use Campsite to review and discuss designs. To gain access:
1. Download the [Campsite app](https://campsite.design/desktop/download).
1. Open it and sign in with your `@zed.dev` email address.
1. You can access our company campsite directly: [app.campsite.design/zed](https://app.campsite.design/zed)