zed-industries/zed
1
1
Fork 0
mirror of https://github.com/zed-industries/zed.git synced 2024-12-29 14:43:55 +03:00
Code Issues Packages Projects Releases Wiki Activity

Add internal markdown docs (#2598)

Browse Source 
This PR adds internal docs directly to the codebase.

There are a few goals here:

- Make it easier to document our internal processes
- Put the documentation where people already are
- Allow changes to be in sync with PRs
- Make it easier for people coming in to discover our docs and onboard
faster.

With 2 more people joining us in the next few weeks it would be great to
get these up.

Release Notes:

- N/A (No public facing changes)
This commit is contained in:
Nate Butler 2023-06-15 10:55:55 -04:00 committed by GitHub
commit 0863486803
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 431 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
docs/backend-development.md Normal file
View File

@ -0,0 +1,52 @@
[⬅ 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

79
docs/building-zed.md Normal file
View File

@ -0,0 +1,79 @@
[⬅ Back to Index](./index.md)
# Building Zed
How to build Zed from source for the first time.
## Process
Expect this to take 30min to an hour! Some of these steps will take quite a while based on your connection speed, and how long your first build will be.
1. Install the [GitHub CLI](https://cli.github.com/):
- `brew install gh`
1. Clone the `zed` repo
- `gh repo clone zed-industries/zed`
1. Install Xcode from the macOS App Store
1. Install [Postgres](https://postgresapp.com)
1. Install rust/rustup
- `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
1. Install the wasm toolchain
- `rustup target add wasm32-wasi`
1. Generate an GitHub API Key
- Go to https://github.com/settings/tokens and Generate new token
- GitHub currently provides two kinds of tokens:
- Classic Tokens, where only `repo` (Full control of private repositories) OAuth scope has to be selected
Unfortunately, unselecting `repo` scope and selecting every its inner scope instead does not allow the token users to read from private repositories
- (not applicable) Fine-grained Tokens, at the moment of writing, did not allow any kind of access of non-owned private repos
- Keep the token in the browser tab/editor for the next two steps
1. Open Postgres.app
1. From `./path/to/zed/`:
- Run:
- `GITHUB_TOKEN={yourGithubAPIToken} script/bootstrap`
- Replace `{yourGithubAPIToken}` with the API token you generated above.
- Consider removing the token (if it's fine for you to crecreate such tokens during occasional migrations) or store this token somewhere safe (like your Zed 1Password vault).
- If you get:
- ```bash
Error: Cannot install in Homebrew on ARM processor in Intel default prefix (/usr/local)!
Please create a new installation in /opt/homebrew using one of the
"Alternative Installs" from:
https://docs.brew.sh/Installation
```
- In that case try:
- `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
- If Homebrew is not in your PATH:
- Replace `{username}` with your home folder name (usually your login name)
- `echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/{username}/.zprofile`
- `eval "$(/opt/homebrew/bin/brew shellenv)"`
1. To run the Zed app:
- If you are working on zed:
- `cargo run`
- If you are just using the latest version, but not working on zed:
- `cargo run --release`
- If you need to run the collaboration server locally:
- `script/zed-with-local-servers`
## Troubleshooting
### `error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`
- Try `xcode-select --switch /Applications/Xcode.app/Contents/Developer`
### `xcrun: error: unable to find utility "metal", not a developer tool or in PATH`
### Seeding errors during `script/bootstrap` runs
```
seeding database...
thread 'main' panicked at 'failed to deserialize github user from 'https://api.github.com/orgs/zed-industries/teams/staff/members': reqwest::Error { kind: Decode, source: Error("invalid type: map, expected a sequence", line: 1, column: 0) }', crates/collab/src/bin/seed.rs:111:10
```
Wrong permissions for `GITHUB_TOKEN` token used, the token needs to be able to read from private repos.
For Classic GitHub Tokens, that required OAuth scope `repo` (seacrh the scope name above for more details)
Same command
`sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
### If you experience errors that mention some dependency is using unstable features
Try `cargo clean` and `cargo build`

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

@ -0,0 +1,34 @@
[⬅ 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 Normal file
View File

@ -0,0 +1,74 @@
[⬅ 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 Normal file
View File

@ -0,0 +1,14 @@
[⬅ 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 Normal file
View File

@ -0,0 +1,96 @@
[⬅ 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.

82
docs/tools.md Normal file
View File

@ -0,0 +1,82 @@
[⬅ 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 memebers!**
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 one password 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)