ref: refresh devenv (#15191)

Author: joshuarli

develop-docs/development-infrastructure/environment/index.mdx

@@ -1,12 +1,12 @@
 ---
 title: Environment
-description: This guide steps you through configuring a local development environment for the Sentry server on macOS and Linux.
+description: This guide steps you through configuring a local development environment for the Sentry server on macOS.
 sidebar_order: 2
 ---
 
-If you're using
-another operating system (Plan 9, BeOS, Windows, …) the instructions are still roughly the same, but we don't maintain any official documentation
-for anything else for now.
+We primarily support development on macOS (arm64 only), but Linux (amd64) should be possible too.
+If you run into any problems on either platform, please open an issue on [devenv](https://github.com/getsentry/devenv/).
+
 
 ## Setup
 
@@ -16,11 +16,17 @@ After installation you should be able to run `devenv bootstrap` which will guide
 
 When you're done with setup, you'll want to also review the <Link to="/development/workflow/">development workflow</Link>.
 
+
 ## Keeping your environment up-to-date
 
-Simply run `devenv sync` inside of your sentry or getsentry repo.
+First make sure your branch is rebased or remerged onto latest `master`.
+
+Running `devenv sync` (which runs `devenv/sync.py`) will bring your environment up-to-date (dependencies, migrations, etc.).
+
+You may also need to run `direnv allow` if you haven't already (sometimes it's easy to miss the prompt).
+
+Any issues? See [troubleshooting](#troubleshooting).
 
-NOTE: After running `devenv sync` you may need to restart your terminal to continue.
 
 ## Running the Development Server
 
@@ -94,9 +100,11 @@ After the server is running we can visit the dev server using `https` at port `:
 
 See also: <Link to="/application/sentry-vs-getsentry/">Sentry vs Getsentry</Link>
 
-Before running `getsentry`, you might need to run `devenv sync` inside the `getsentry` directory if you have previously run `sentry` locally, as there might be differences between the environments.
+To set up and keep getsentry up to date, you need to run `devenv sync` inside `sentry` before you run `devenv sync` inside `getsentry`.
+
+`getsentry` depends on what commit `../sentry` is checked out to, so keeping your sentry repo up to date is important.
 
-Just like running `sentry` (see above), you can start the `devservices` using the following command in the `getsentry` folder:
+Just like running `sentry` (see above), you can start the `devservices` using the following command in the `getsentry` repo:
 
 ```shell
 devservices up
@@ -120,7 +128,9 @@ After that, you can start the development server inside the `getsentry` folder:
 devservices serve
 ```
 
-**Note**: You **cannot** have both sentry and getsentry devserver running at the same time.
+<Alert title="Note">
+You **cannot** have both sentry and getsentry devserver running at the same time.
+</Alert>
 
 After the server warms up, access it at [http://dev.getsentry.net:8000](http://dev.getsentry.net:8000/). Using localhost won't work. Note that the **http** protocol is used, not **https**. If you encounter a certificate error while accessing it locally, it might be because your browser has remembered that `dev.getsentry.net` previously used the https protocol (possibly while running `pnpm dev-ui`) and is now redirecting all http requests to https. To resolve this, open the site in an **incognito window** of your browser.
 
@@ -175,7 +185,7 @@ SENTRY_SILO_DEVSERVER=1 SENTRY_SILO_MODE=REGION SENTRY_REGION=us getsentry djang
 
 ## Troubleshooting
 
-The more up-to-date troubleshooting docs for the internal development environment on MacOS are <Link to="https://www.notion.so/sentry/devenv-troubleshooting-1448b10e4b5d8080ba04f452e33de48d">here</Link>.
+The more up-to-date troubleshooting docs for the _internal_ development environment on MacOS are <Link to="https://www.notion.so/sentry/devenv-troubleshooting-1448b10e4b5d8080ba04f452e33de48d">here</Link>.
 
 You might also be interested in <Link to="/development/continuous-integration/#troubleshooting-ci">Troubleshooting CI</Link>.